The project file¶
A project is one UTF-8 JSON file (.json, 2-space indent) with the sprite sheets it names. This page documents format 9, the format since version 0.12, and the rules that turn it into pictures and motion. The editor is the reference: what it shows is what these rules give.
Basics¶
- Images are named by paths relative to the project file.
- References are string ids, unique within their list: module ids among the modules, part ids within their frame, keyframe ids within their object, and so on. New ids are random (
mod_3f9a...); treat them as opaque strings. - Unknown keys are ignored when the editor loads a file and dropped when it saves.
- Versions:
format_versionsays which format a file has. The editor upgrades older files when it opens them; a file of a newer format opens with a warning, and what the older editor does not know is lost when it saves. Most changes since format 3 only added keys; the repository'sdocs/FILE_FORMAT.mdlists every version and what an older editor makes of a newer file. - Order matters in several lists: parts are drawn back to front, the export numbers types in list order, and modules, frames, animations, scenes and mappings keep the numbers their position gives them.
Top level¶
{
"format_version": 9,
"name": "Prince of Persia",
"console": "megadrive", // the target console: megadrive, snes, nes, gba, gb
"console_setup": "md_h40", // its setup: md_h40, md_h32, snes_8_16 ... snes_32_64, nes_8x8, gba, gb_8x8 ...
"images": [],
"palettes": [],
"palette_swaps": [],
"modules": [],
"frames": [],
"animations": [],
"timeline_scenes": [],
"mappings": [],
"collision_types": [], // hitbox types
"point_types": [],
"event_types": [] // animation event types
}
An unknown console_setup stands for the console's first setup.
Images and palettes¶
"images": [
{"id": "img_1", "file_path": "modules_POP.bmp", "width": 778, "height": 635,
"transparent_color": [255, 0, 255], // the key colour, or null (then the image's alpha)
"palette_id": "pal_1"}
],
"palettes": [
{"id": "pal_1", "name": "Palette 1",
"colours": [[r, g, b], ...], // slots 1, 2, ...; slot 0 is transparent and not stored
"cycles": [{"first": 3, "count": 4, "frames": 8, "reverse": false}]}
],
"palette_swaps": [
{"id": "swap_1", "name": "Blue guard",
"palettes": {"pal_1": {"colours": [[36, 36, 218], null, ...], // per slot: its colour, or null = the palette's
"cycles": null}}} // null: the palette's cycles; a list: its own
]
- Every image belongs to one palette; vector shapes use the first.
- A pixel's slot is the first slot with exactly its colour, else the nearest colour by squared RGB distance. Pixels equal to the key colour are transparent.
colours: nullis an automatic palette: the editor builds it from its images (the most used colours first, at most as many as the console shows) and stores them in slot order once the project is open. Slots are fixed from then on: swaps and cycles refer to them.- A palette may store more colours than the console shows (kept from a console with bigger palettes); only the first are used.
- A colour cycle rotates
countslots fromfirstby one slot everyframesvideo frames, towards the last slot (the first, whenreverse).
Modules¶
{"id": "mod_1", "name": "0cap01", "image_id": "img_1",
"rect": [x, y, w, h], // in sheet pixels
"pivot": [px, py], // relative to the rectangle's top left
"type": "MD_IMAGE",
"rotated": false,
"color": [r, g, b], // shapes only
"params": []} // shapes only
- The picture of an image module is its rectangle of the sheet, with the key colour made transparent. With
rotated(set by sheet packers) the picture is that rectangle turned 90° anticlockwise; the pivot is given for the picture as used. - Shapes are drawn in a
w×hpicture incolor, one pixel wide:MD_RECTandMD_FILL_RECTthe rectangle;MD_MARKERits two diagonals;MD_ARCandMD_FILL_ARCan ellipse's pie slice fromparams[0]degrees,params[1]degrees long (0 and 360 by default);MD_TRIANGLEandMD_FILL_TRIANGLEthe triangle through three points given as percentages of the size (params: six numbers);MD_LINEthe line between two points given the same way (four numbers).
Frames¶
{"id": "frm_1", "name": "stand01", "group": "", "store_whole": false,
"fmodules": [
{"id": "fmod_1", "ref_type": "module", "ref_id": "mod_1", // or "frame": a nested frame
"position": [x, y], "flip_x": false, "flip_y": false, "rotation_degrees": 0.0}
],
"collision_rects": [{"id": "crect_1", "type_id": "ctype_1", "rect": [x, y, w, h], "role": "body"}],
"control_points": [{"id": "pt_1", "type_id": "ptype_1", "x": 0, "y": 0, "role": "feet"}]}
fmodulesare the parts, back to front: the last is drawn on top.grouponly sorts the editor's lists.store_wholeasks the console exports to store the frame as one picture per palette.- Hitbox and point roles are free names (
"": none); their types are ids fromcollision_typesandpoint_types(a missing type is an unknown type). - Nested frames never form a cycle; the editor refuses one.
Drawing a frame¶
Draw the parts in order, each with its transform, about the frame's origin (0, 0), with y downward:
- A module part: the module's picture (under the mapping being drawn, below) is mirrored in place by its flips: its bounds stay where they are, whatever the pivot. Then it is turned by
rotation_degreesabout its pivot, in steps of 90° (use exact values, never a computed cosine). The pivot lands onposition. - A nested frame part: the nested frame is drawn whole and transformed about
position: flipped first, then turned. Inside a mirrored frame (an odd number of flips on the way down) its children's turns go the other way. - Hitboxes are areas: their corners transform with the frame. Points mark pixels: a transform moves the pixel's centre (
x + 0.5,y + 0.5) and floors, so mirroring mapsxto-x - 1and a clockwise quarter turn maps(x, y)to(-y - 1, x).
The editor turns parts in 90° steps only. A part at another angle (from an imported file) is drawn by the console exports as a picture of its own, turned about its pivot.
Animations¶
{"id": "anim_1", "name": "run", "group": "",
"playback_type": "loop", // forward | backward | loop | ping_pong
"loop_count": 0, // passes before a repeating playback ends; 0 = never
"fps": 10, // ticks per second
"loop_start": 0, // loop: later passes start at this step
"next_animation_id": null, // continues with this animation when it ends
"aframes": [
{"frame_id": "frm_1", "duration_frames": 1, // the hold, in ticks
"offset": [x, y], "flip_x": false, "flip_y": false, "rotation_degrees": 0.0,
"events": [{"type_id": "evt_1", "value": 0}]}
]}
A step shows its frame flipped, then turned, about the frame's origin, then moved by offset (root motion). An fps of 0 counts as 10.
Animation playback¶
These are the rules the editor's preview and both runtimes follow, tick for tick (the editor's playback.py and the runtimes' ms_anim_player_tick are tested against each other):
- A step holds for
duration_framesticks; anything below 1 counts as 1. - Start: at step 0, or at the last step for
backward. - forward (play once): after the last step the animation ends.
- loop: after the last step, a pass is complete; it continues at
loop_start(clamped to the steps), so the steps before it play only in the first pass. - backward: plays from the last step down; after step 0 a pass is complete and it continues at the last step.
- ping_pong: plays up, then down, without repeating the end steps (0 1 2 1 0 1 2 ...); a pass is complete when it comes back down to step 0. An animation of one step stays on it.
- Ending: a repeating playback ends when its completed passes reach
loop_count(when that is above 0). An animation that ends continues withnext_animation_idfrom its start; without one, playback stops on its last shown step. - Events fire on the tick their step starts and are active while it shows;
valueis a free number for the game.
On the consoles the runtimes count video frames: the exports convert each step's hold to max(1, round(duration_frames × 60 / fps)) video frames. Rates that divide 60 (10, 12, 15, 20, 30, 60) are exact; others round some steps, which the editor's preview plays the same way.
Scenes¶
{"id": "scene_1", "name": "Swordfight", "fps": 12, "duration_seconds": 10.0,
"duration_frames": 120, // derived, written for convenience
"loop": true, "background_color": [32, 32, 32],
"objects": [
{"id": "tlo_1", "name": "Prince", "parent_id": null,
"source_type": "animation", "source_id": "anim_1", // none | module | frame | animation
"mapping_id": null, // null: the parent's (at the top: the one being drawn); "original"; or a mapping id
"palette_swap_id": null, // the same, for palette swaps
"attach_point_role": "", // follow this point role of the parent's frames ("" = none)
"attach_point_type": null, // and this point type (null = any)
"draw_order": 0, "playback_offset": 0.0, "playback_speed": 1.0,
"playback_mode": "as_animated", // as_animated | loop | once | ping_pong | backward
"path_mode": "linear", // linear | spline
"use_source_root_motion": false,
"keyframes": [
{"id": "tlk_1", "time": 0.0, "x": 0.0, "y": 0.0, "rotation_degrees": 0.0,
"flip_x": false, "flip_y": false, "visible": true,
"easing": "linear",
"path_in": null, "path_out": null, // spline handles in the parent's space, or null = automatic
"source_type": null, "source_id": null, // switch the source at this key (null = no change)
"source_offset": [0.0, 0.0],
"scale_x": 1.0, "scale_y": 1.0, "opacity": 1.0} // reserved: not drawn
]}
]}
Times are seconds. The console exports bake every scene into one picture per tick of its fps, so a game usually never evaluates scenes; an engine that wants to stage them itself follows these rules (the reference is models/timeline.py in the source code):
- A segment between two keys eases by the end key's
easing:step,linear, or a shape (quad,cubic,quart,quint,sine,expo,circ,back,elastic,bounce) with_in,_outor_in_out. - With
path_mode: "spline"a segment with a handle (path_outof its start key,path_inof its end key) is a cubic Bézier; otherwise it follows a Catmull-Rom curve through the neighbouring keys, except that two keys at the same position hold still. - Flips and visibility change at a key and hold until the next.
- An object's animation plays from the scene start, shifted by
playback_offsetand scaled byplayback_speed; a source switched in at a later key plays from that key.as_animatedplays the animation's own playback, repeat count, loop-from step and follow-ups; the other modes override them and never hand over to a follow-up. - With
use_source_root_motionthe current step's offset, flips and turn apply inside the object, like a nested frame in a frame, and the key'ssource_offsetis added to the step's offset the same way. - A parent's transform carries its children. Objects are drawn by ascending
draw_order(ties by name, then id), back to front; the editor keeps it the depth-first order of the layer tree, a parent before its children. - An object with
attach_point_rolesits on that point of its parent's current frame: its key positions are offsets from the point, inside the parent's transform; while the parent's frame has no such point the object does not show.
Mappings¶
{"id": "map_1", "name": "Guard",
"map": {"mod_a": "mod_b", // draw mod_b wherever mod_a is used
"mod_c": null}} // hide mod_c; a module not listed stays as it is
A mapping replaces modules wherever they are drawn, in nested frames too: the replacement is drawn at the original's part, with the part's position, flips and turn, its own pivot landing on the position. Mapping a module to a module that is itself mapped does not chain.
Types¶
"collision_types": [{"id": "ctype_1", "name": "Hurt", "color": [255, 0, 0]}],
"point_types": [{"id": "ptype_1", "name": "Weapon", "color": [0, 255, 0]}],
"event_types": [{"id": "evt_1", "name": "hit", "color": [255, 110, 100]}]
The colours are the editor's. The console exports number each list in its order (MS_HITBOX_HURT, MS_POINT_WEAPON, MS_EVENT_HIT) and the roles alphabetically.
Not in the file¶
The editor keeps the preview's mapping and palette swap, and each tab's view (selection, zoom, grid), in its own preferences, per project file. Nothing in a project depends on them.