Maps and Blender¶
dc2tk setup exports the game's 3D maps into extracted/maps/<map-code>/ as .gltf scenes for Blender, for reference. To change a map, export it into a mod.
Quick steps¶
- Export the map into your mod folder:
- Open
mods/my-mod/maps/m01/m01.gltfin Blender with the dc2tk add-on, edit placements, trigger points, collision, meshes, or textures, and press Export Map to Mod. The add-on writes the scene back and adds the map's line tomods/my-mod/mod.json: (Without the add-on, export the scene as glTF Separate with custom properties and +Y up, and add the line yourself.) - Build the ISO with
dc2tk build. It rewrites only what changed: the.mapfile, edited or new models, and edited or new textures. An unedited scene changes nothing.
To see a change in the game without building an ISO, press Play in Game (F5) in the add-on instead of step 3. It exports the map, builds it into the native port's override folder, and shows it in the port's debug build with the player at the 3D cursor, starting the game first if it is not running. Press F5 again after each edit; Cursor to Player takes the 3D cursor back to where the player stands in the game. This needs the debug build (python3 -I tools/port.py --movies --debug) and the retail ISO set in the add-on's preferences.
dc2tk map-export --list lists every map with its title. Dungeon floor libraries such as d01f01 are not in extracted/maps; export them the same way (see Dungeons).
Installing the Blender add-on¶
- Download
dc2tk-<version>-blender.zipfrom GitHub Releases. - In Blender (4.2+), open Edit > Preferences > Add-ons, click the menu at the top right, choose Install from Disk, and select the zip file.
- In the add-on's preferences (DC2 Maps (dc2tk)), set the dc2tk repository folder to your unzipped
dc2tkrelease. - Press
Nin the 3D Viewport and open the DC2 tab. Pick a map from the list and press Import.
The add-on also checks a map against the game's limits (Validate Map), shows what a build would change (Preview Changes), and builds the ISO. See its README for everything it does.
The glTF scene¶
The scene root is map:<name>, with four groups:
| Group | Contents |
|---|---|
placements |
The map's placed parts (place:NAME), each holding its pieces: visible models, and collision meshes (kind: collision for floors and walls, kind: camera for camera collision). |
points |
Trigger points (point:NAME): doors, chests, save points, lights, sounds, spawn positions, and more. A point's extras.c2 holds its kind and data (a door's program and target). |
cameras |
Fixed camera positions. |
sky |
The sky, for display only; it is never built. |
Placements keep their slot numbers because scripts address them by slot: deleted placements stay in the map, hidden, and new ones are added at the end.
A map of a mod's own¶
A new map¶
Add a new map under "add" in mod.json, using an existing map as a "like" template:
{
"add": {
"map:fishroom": {
"file": "maps/fishroom/fishroom.gltf",
"like": "m07",
"title": "The Fish Room",
"script": "fishroom.c",
"programs": {
"door_out": "LEAVE_FISH_ROOM"
}
}
}
}
| Option | Meaning |
|---|---|
"like" |
The disc map to copy as a base. |
"title" |
The map's title in the map table (defaults to the "like" map's). |
"script" |
The C file in your mod that becomes the map's script. |
"programs" |
Script programs for the scene's event points, by point name: a number, or a NEW_PROGRAM name. |
"compact" |
true drops deleted placements instead of keeping them hidden. |
A map name is lowercase letters, digits, and _, at most 12 characters, and not a map on the disc. Scripts see the new map's number as MAP_<NAME> (MAP_FISHROOM). In the Blender add-on, New Map from This One writes this entry and a starter script for you.
A new map's own script¶
The "script" file is a complete map script, compiled once per language. When the map loads, the engine runs its map_start program, which must place the player (place_chara), position the camera, and fade in the screen, like the game's town scripts. See The Spinning Cult (fishroom.c) for a working example.
Doors between maps¶
A door is an event point of kind door in a map's scene, plus a program in that map's script:
- Add the door point in Blender (Add > DC2 > Door), or use Door to Another Map, which also writes the program and the
"programs"entry. - Name the door's program on the map's line in
mod.json, so the scene never holds a generated number: - Write that program in a script patch for the map. It jumps to the new map:
Declare NEW_PROGRAM(ENTER_FISH_ROOM) in a header the mod's scripts share (here cult.h). The way back works the same: a door in the new map whose program jumps back to the town. See the spinning-cult mod's m01.c and fishroom.c.
Limits¶
- At most 320 placements in a map (400 in dungeons), and template names of at most 31 characters.
- Keep the names of placements, pieces, and points that the map's scripts use.
dc2tk buildchecks every map memory budget (see Memory Limits).
Scene reference¶
For editing a scene as raw JSON, or writing tools for it. Every exported node carries extras.c2, whose "role" says what it is:
| Node | Name | extras.c2 |
|---|---|---|
| Scene root | map:NAME |
{"role": "map", "map": {...}}: the .map file's settings, images, packs, light sets, and cameras |
| Group | placements, points, cameras |
{"role": "group"} |
| Placement | place:NAME |
{"role": "placement", "template", "show", "group", "far_clip", "slot"}; its transform is the placement's |
| Piece | piece:NAME |
{"role": "piece", "model", "kind", "show", "time", "col_type", "materials"}; kind is model, collision, camera, or chara; its children are the model's nodes |
| Model node | the node's full name | {"role": "mds", "mds_index": n}; meshes are shared by every piece that places the model |
| Trigger point | point:NAME |
{"role": "point", "kind", "enable", "flag", "data": {...}}; under its placement when part of a template, else under points |
| Fixed camera | camera:INDEX |
{"role": "camera", "index"} at the camera's position |
| Sky | sky, sky:day, ... |
{"role": "display"}: never built |
- Units and axes: 1 glTF unit is 1 game unit (a dungeon cell is 320 across), Y up, as in the game. Rotations are written back as the game's Euler angles; nodes that did not move keep their original numbers.
- Names and order: Blender renames duplicates (
.001) and sorts children by name, so every node keeps its exact name inextras.c2.nameand its position inextras.c2.order. New nodes take their Blender name without the role prefix and.NNNsuffix, and go after the existing ones. - Templates: Each placement holds its own copy of its template's pieces and points. A change made the same way in every placement of a template changes the template; a change in only some placements makes a new template for them.
- Collision: A collision piece's material names hold its attributes (
col_ground0_foot2_area6_mask12). See DC2 Internals: Maps section 4.3 for what they mean. - Point data (
data, by the point'skind):event:kind(door,t_box, ...),event_no,program,args[3],target,flags[3]invent:id,min[3],max[3],unknown_int,unknown_float,angleplight:power,color[3](0–511),mode,args[4],flicker,depth,periodsound:number,near,far,unknown_int,shape,start[3],end[3]anime:placement,piece,frame,drives,mode,start[3],step[3],end[3], anduniform,relativewhen presentfire,flare:color[3],draw,extra[2];effect:effect;pos: none
- Other fields: a point's
flagis[a, b, start_hour, end_hour]; a piece'stimeis[start, end]; a placement'sfar_clipis[distance, fade]ornull; a piece'scol_typeis an integer,[type, param], ornull.
See DC2 Internals: Maps for .map, .pcp, .mpk, and .ipk binary specifications.