Step-by-Step Conversion Tutorial

May 5, 2026 · View on GitHub

This detailed tutorial walks you through converting a Java mod to Bedrock using PortKit. We'll use a simple "Custom Sword" mod as an example.

Example Mod: Ruby Sword

For this tutorial, we'll convert a simple Java mod that adds:

A new sword item (Ruby Sword)
Custom texture
Attack damage and durability

Step 1: Prepare Your Java Mod

What You Need

Your mod should include:

Java source files (.java) - the mod logic
Resource files - textures, models, sounds
mod metadata - mcmod.info, fabric.json, or forge.mods.toml

Example Structure

rubysword.jar
├── assets/
│   └── rubysword/
│       ├── textures/
│       │   └── items/ruby_sword.png
│       └── models/
│           └── item/ruby_sword.json
├── com/example/rubysword/
│   ├── RubySword.java
│   ├── RubySwordItem.java
│   └── RubySwordMod.java
└── META-INF/
    └── mods.toml

Step 2: Upload to PortKit

Navigate to portkit.cloud
Click "Upload Mod" or drag-and-drop your .jar file
Wait for analysis (30-60 seconds)

What the Analysis Shows

Mod Analysis Complete
├── Detected Features
│   ├── Items: 1 (Ruby Sword)
│   ├── Blocks: 0
│   ├── Entities: 0
│   └── Recipes: 0
├── Complexity: Simple
├── Estimated Time: 5 minutes
└── Conversion Confidence: 95%

Step 3: Review Conversion Plan

Before starting, review the AI's plan:

Detected Components

Component	Java Class	Bedrock Equivalent	Confidence
Ruby Sword Item	RubySwordItem	items/ruby_sword	95%
Texture	ruby_sword.png	textures/items/ruby_sword.png	100%
Model	ruby_sword.json	models/item/ruby_sword.json	90%

Potential Issues

High confidence: No issues expected
Medium confidence: May need manual texture adjustment
Low confidence: Custom attack logic may need tweaking

Step 4: Start Conversion

Click "Start Conversion" and monitor progress:

Phase 1: Java Analysis (1 minute)

✓ Parsing Java code
✓ Building AST (Abstract Syntax Tree)
✓ Analyzing dependencies
✓ Extracting item properties

Phase 2: Bedrock Generation (2 minutes)

✓ Creating behavior pack items/
✓ Generating JavaScript item logic
✓ Converting texture format
✓ Creating resource pack structure

Phase 3: Asset Conversion (1 minute)

✓ Processing textures (PNG optimization)
✓ Converting JSON models
✓ Validating file formats

Phase 4: Validation (1 minute)

✓ Syntax checking (JavaScript)
✓ Schema validation (JSON)
✓ Asset integrity check
✓ Packaging into .mcaddon

Step 5: Review Conversion Report

Once complete, you'll see a detailed report:

Success Summary

Conversion Complete!
Overall Success Rate: 95%
Components Converted: 3/3
Manual Steps Required: 0

Component Inventory

File	Type	Status	Notes
`behavior_packs/rubysword/items/ruby_sword.json`	Item Definition	✓ Success	-
`behavior_packs/rubysword/scripts/main.js`	JavaScript Logic	✓ Success	Attack damage converted
`resource_packs/rubysword/textures/items/ruby_sword.png`	Texture	✓ Success	Optimized for Bedrock

Assumptions Made

The AI explains its decisions:

Attack Damage: Converted from Java 10 to Bedrock attack damage 10
Durability: Mapped to max_durability component
Creative Tab: Assigned to "equipment" category

Manual Steps (if any)

For simple mods like this, you'll see:

No manual steps required! Your add-on is ready to use.

For complex mods, you might see:

⚠ Manual Steps Required:
1. Custom rendering logic needs JavaScript implementation
2. GUI elements need Bedrock forms (not Java GUI)
3. Network packets need Bedrock scripting API

Step 6: Download and Test

Download the .mcaddon File

Click "Download Add-on" to save rubysword.mcaddon (usually 50-200KB).

Install in Bedrock Edition

Windows 10/11:

Double-click the .mcaddon file
Minecraft Bedrock opens automatically
Click "Import" to install

Mobile (iOS/Android):

Share the file to Minecraft
Open Minecraft → Settings → Storage → Behavior Packs
Activate "Ruby Sword"

Console:

Upload to a file sharing service
Download in Minecraft Marketplace → My Packs

Test the Conversion

Create a Test World:

Enable cheats and Experimental Features:
- Create new world
- Cheats: ON
- Experimental: "Holiday Creator Features" ON
- "GameTest Framework" ON (if testing)
Obtain the item:
```
/give @p rubysword:ruby_sword
```
Test functionality:
- Does the sword appear in your hand?
- Does it deal correct damage?
- Does durability decrease?
- Does the texture look right?

Common Issues and Fixes

Item doesn't appear:

Solution: Check that Experimental Features are enabled

Texture is missing:

Solution: Verify resource pack is activated in world settings

Wrong damage values:

Solution: Edit behavior_packs/rubysword/items/ruby_sword.json
Adjust the "minecraft:attack_damage" component

Step 7: Iterate and Improve

If something isn't perfect:

Option A: Edit the Generated Files

Extract the .mcaddon (it's a ZIP file)
Edit the JSON/JavaScript files
Re-package as .mcaddon

Example - Adjusting Attack Damage:

File: behavior_packs/rubysword/items/ruby_sword.json

{
  "format_version": "1.16.0",
  "minecraft:item": {
    "description": {
      "identifier": "rubysword:ruby_sword"
    },
    "components": {
      "minecraft:attack_damage": 12,  // Changed from 10
      "minecraft:max_durability": 1500,
      "minecraft:durability": {
        "max_durability": 1500
      }
    }
  }
}