The Modbox

The Modbox is a folder containing a mod example based on V4 assets plus useful source files. Organize your own assets based on this specific file structure. Then you'll be able to import and try the modbox directly within the Incredibox app available on Steam. This way, you can see exactly how your mod will look in the real app.

By downloading the modbox, I acknowledge I have read, understood and accepted the Incredibox GTU.

App.json

modbox/app.json

You have to edit the app.json file to change information about the mod such as title, modder credits, loop duration, number of animations, bonuses, path to files, etc. Example below:

{
    "name": "Modbox",			// Your mod name
    "date": "2025-19-05",		// Mod release date "year-month-day"
    "looptime": 8000,			// Sound loop duration in milliseconds
    "bpm": 120,				// Rhythm (Beats Per Minute) of the music [only for info]
    "totalframe": 384,			// How many frames per animation (in principle: looptime x 2 x 24ips)
    "bonusloopA": true,			// true if bonus can only start on loopA and not on loopB (depends on your musical composition)
    "bonusendloopA": false,		// true if you want to force the metronome to restart a loopA after a bonus has finished when it should in principle have been a loopB (really rare)
    "colors":["#D8A365", ...],		// List of hexadecimal colors for your mod UI (max 6)
    "animearray": [			// List of sound/animation files (max 20)
        {
            "name":"drum1_kick",	// name of the animation/sound file (without extension) stored in both the anime/ and sound/ folders
            "color":"#E5A90E",		// hexadecimal pictogram color
            "uniqsnd":false 		// true if sound composed with only one loop, false if composed with 2 loops (A and B)
        },
        { ... }
    ],
    "bonusarray": [			// List of bonuses (max 3) "bonusarray" can be removed if you don't have bonuses
        {
            "title": "Love",		// Title of the bonus [only for info]
            "code": [1,2,6,11,17],	// Array of 5 picto ids to unlock the bonus
            "name": "b1-love",		// File name of the mp4 video file (without extension) stored in the bonus/ folder
            "sound": "bonus1_love",	// File name of the bonus sound (without extension) stored in the sound/ folder
            "predrop": "bonus_predrop",	// File name if a sound should play before the bonus launch
            "loop": 1			// How many loops the bonus lasts
        },
        { ... }
    ],
    "credit":{				// Modder info
        "crewname": "ARP modders",	// Modder crew name
        "process":["Allan", "Romain"],	// Roles of modders (names needs to be separated by double-quotes and commas so users can search for a specific modder's name using the search form)
        "music":["Paul"],		// Just remove a "role" if not needed
        "design":["Romain"],
        "animation":["Allan"],
        "thanks": "To the best community ever"
    }
}

Image

modbox/image/

You can replace files within the image/ folder with your own (mod icon, home screen, picto, etc.). We provide you with some original source files (Adobe Illustrator) so you can better understand how to make them. Take care to respect the object position in the page, image size exported, extension file (jpg vs png) and file names (images in this folder need to keep their original name and their original size/resolution).

Sound

modbox/sound/

You can use any music editing software to record, edit and export your sound loops (only MP3 files are accepted). Replace the files in the sound/ folder with your own. The names of your audio files must match the key/value name in animearray from app.json

---

Loops mechanism

• All loops have the same duration (neither too short nor too long, do something consistent for the user experience).
• The duration of your loops must be set using the looptime key/value from app.json.
• Incredibox’s music engine launches a looping metronome based on the looptime duration.
• Each time the metronome does a loop (each bar), it switches between 2 states: loopA, loopB, loopA, loopB, etc… This allows for more variations within the musical composition. For example, you can have a basic beat with a binary rhythm during loopA (first bar), making a small change during loopB (second bar). This means that, if your sound never changes from loopA to B, include only one sound file in the folder (uniqsnd: true in app.json). Otherwise, include 2 sounds with stateA and stateB. Analyze the following diagram: during loopB, the metronome will play stateB of a sound if it exists: otherwise, it will play stateA.

|1		|2		|3		|4		|5		| ... |
|loopA		|loopB		|loopA		|loopB		|loopA		| ... |
|beat_stateA	|beat_stateB	|beat_stateA	|beat_stateB	|beat_stateA	| ... |
|voice_stateA	|voice_stateA	|voice_stateA	|voice_stateA	|voice_stateA	| ... |

---

Bonus music mechanism

• The audio duration of your bonus must be a multiple (x1, x2, x3, x4, etc) of your sound loops.
• The bonus can be launched in loopA or both A and B (see bonusloopA in app.json).
• You can launch a sound called predrop during the loop before the bonus starts (see predrop in bonusarray from app.json).
• Example with a 2-loop bonus which must start at loopA with a predrop sound.

|1		|2		|3		|4		|5		| ... |
|loopA		|loopB		|loopA		|loopB		|loopA		| ... |
|beat_stateA	|beat_stateB	|		|		|beat_stateA	| ... |
|voice_stateA	|voice_stateA	|		|		|voice_stateA	| ... |
|		|predrop	|bonus_playing	|bonus_playing	|		| ... |

Bonus

modbox/bonus/

You can use any video software to edit and export your video (we recommend using Adobe Animate). Replace files in the bonus/ folder with your own. Your video must be 2000x800px, in MP4 format only. Your video must not include any audio tracks.

• You can include up to 3 videos in your mod (if 0, just remove bonusarray in app.json).
• The duration of your video must be a multiple (x1, x2, x3, x4, etc) of your sound loops.
• Bonuses can have different lengths (see loop in bonusarray).
• The names of your video files must match the key/value name in bonusarray.
• Beside your MP4 video file, put an SVG file (70x70px) with the same name, containing the vector icon (56x56px maximum) for the bonus.

Anime

modbox/anime/

In this folder, you have to organize your animated character files (aka the polos). The Incredibox graphics engine works with a homemade mechanism. You have to use Adobe Animate to open and edit our .fla source file. It will let you save so much time on lipsync and you'll never again have to edit every sprite.json file manually 😅

• You can include a maximum of 20 polos in your mod.
• SWF file size must be 164x380px (will be 328x760px once exported as a PNG sprite).
• Prefer vector assets within the SWF so you don't have to worry about resolution.
• The names of your animation files must match the key/value name in animearray.
• Convert your SWF to a PNG sprite with our SWF2sprite tool.

---

Custom polo sprite

modbox/anime/0_polo.png (1312x960px)

You can customize the original polo sprite file by editing the .ai source file provided in the anime folder. Edit and export your new 0_polo.png sprite to overwrite the existing file.

---

Make animation

Open and edit the polo-template.fla with Adobe Animate. The specific tree structure and object names in this file are required for the final exportation steps (SWF to PNG sprite). You just have to hit CTRL+ENTER to export and run the SWF file of your animation. Keep this file structure and organization:

file.fla
└── stage
    └── polo
        ├── headanim
        │   └── limit
        ├── headwait
        └── costume

---

Convert animation to sprite (SWF2Sprite)

Once your animation looks great, you can convert your SWF into a PNG sprite file. Open our SWF2sprite tool (you need an SWF reader such as Adobe Flash/Animate installed on your computer) and click Convert to select your SWF animation file. If you've respected the file tree structure and object names from the polo-template.fla, you should see the SWF2sprite analyzing your animation. It will compare each face to save only different ones before exporting a PNG file (try not exceed more than 40 faces per sprite). Plus, the tool will generate and export a JSON file filled with all data needed by the Incredibox graphics engine (such as polo's head xy position, head height, crop size, etc…).

---

Include animation

Once you have exported your animation PNG sprite and JSON data, you can put this file into the anime/ folder. Don't forget to add your animation name by editing the key/value name of the animearray array in the app.json file. Import your mod folder into the Incredibox app for Steam to check your animation.