Maps: .map, .pcp, .mpk, .ipk, collision¶
This page documents the map file formats and runtime systems: which files the engine loads for a map, how templates and pieces are placed and checked for collision, and what the engine requires for a new map. All engine source citations refer to the ps2/ directory of the ChronicleTwo decompilation (paths below are relative to ps2/). All counts come from analysis scripts run across the entire extracted PAL disc corpus.
- Map meshes use the MDS format documented in models; this page covers map-specific behavior.
- Random dungeon floors are generated at runtime from template libraries; see dungeons.
- For instructions on editing existing maps and creating new ones, see modding maps.
Not yet known: How the VU microprogram combines vertex color with dynamic lighting is not yet traced. In addition, the int and float parameters of invent points and the int parameter of sound points are unnamed.
1. Files of a map¶
A map named s17 resides at map/<first letter>/<letters 1-3>/<letters 4-6>/. The engine uses the third directory level only when the map name has six or more characters (GetMapPath, mapselect.cpp:197). For example, s17 is at map/s/s17/, m05x is at map/m/m05/m05x.map, and i03h02 is at map/i/i03/h02/i03h02.map:
| File | Contents |
|---|---|
s17.map |
Text script: part templates, placements, trigger points, lights, fog, and cameras |
s17.mpk |
Pack of model packs (s17_0.pcp), containing info.cfg and .mds meshes |
s17.ipk |
Pack of texture archives (.img) |
s17.efp |
Pack of effect scripts (.em) and effect textures |
s17.sky |
Sky pack (info.cfg, meshes, and .img), present when the map has a sky |
s17.cfg |
Extra map data: trigger events, water surfaces, river parts, and occlusion planes |
s17*.stb |
Map event scripts (one per language) |
File counts under map/ on the PAL disc¶
| Extension | Count | Notes |
|---|---|---|
.mds |
13,372 | 3D mesh and collision files |
.stb |
962 | Map event bytecode scripts |
.img |
549 | Stored inside .ipk, .efp, .sky, and .chr packs |
.cfg |
434 | 222 PCP info.cfg files, 75 .chr/.sky info.cfg files, and about 70 map-level .cfg files |
.pcp |
223 | Includes one unused empty i01h02.pcp |
.mpk, .ipk, .map |
210 each | Main map archives and scripts |
.chr |
90 standalone | Plus 67 inside .pcp packs |
.sky |
56 | Sky model and texture packs |
.gpi |
38 | Georama part info files |
.em |
26 | Effect scripts |
.efp |
22 | Effect packs |
- Unused build artifacts: Files with extensions
.pcl,.ptl,.mpp,.mpl,.mapb,map.lst,map.cfg_,make.bat, and.divare unused build artifacts that contain the developers'Y:\drive paths. - Unreachable
.mapfiles: Six map files sit at paths thatGetMapPathnever reaches (d/d02/f01r/d02f01r.map,d/d06/b01/m07.map,i/i04/h02/i01h02.map,m/m06/m07.map,s/s38/i03h02.map, ands/s43/i03h02.map).
Loading (CScene::LoadMapFromMemory, GetLoadMapInfo at mapjump.cpp:147)¶
- Read the map's
.map,.cfg,.mpk,.ipk,.efp, and.skyfiles. If the map table (map<language>.cfg) specifies an add map, also read the add map frommap/cmn/<path>. - Run the settings pass of the
.mapfile (section 2.1). - Load the texture archives (
.ipk) and model packs (.mpk) of both the main map and the add map into one shared model list. - Allocate the placement table: 320 slots for standard maps, or 400 slots for dungeons and the title screen.
- Run the parts pass in order: first the add map (
map.cpp:1352), then the main.mapfile, then the map's.cfgfile, and finallyPlacePartsEnd.
Map registration table (map0.cfg–map6.cfg):
- Each file (one per language) contains 189 entries (
map/map.cfghas 86 entries and is an unused older table):MAP_NAME "name","title","add_path",type,sel_type[,snd_id[,area_no]] - A map's ID number is its 0-based row index in this list, so a new map must be appended to the end (section 7).
- Twenty-two
.mapfiles on the disc are not listed inmap<language>.cfg(dungeon variants and debug maps that the engine loads directly by name). - The file
snd2/MAP_index.txtassigns sound sets according to a map'ssnd_id.
2. The .map file¶
A .map file is a text tag script (KEYWORD a,b,...;) that CScriptInterpreter (scriptinterpreter.cpp) parses in two passes. Each pass skips the tags belonging to the other pass (any unrecognized tag is skipped up to its terminating ;).
| Pass | Tag Table | Source | Parsed Content |
|---|---|---|---|
| 1 (Settings) | mapinfo_tag |
mapinfo.cpp:73 |
Textures (IMG), model packs (PCP), lights, and environment settings |
| 2 (Parts) | map_tag |
mapload.s |
Part templates (PARTS), pieces, placements (MAP_PARTS), cameras, and trigger points |
Token rules:
- Tag names: Start with an uppercase letter (
A–Z). - Strings: Double-quoted text (
"..."). Shift-JIS bytes are allowed inside quotes. - Numbers: Unquoted text containing a
.parses as afloat, and other unquoted numeric text parses as anint. Integers and floats convert freely. - Scientific notation bug: Unquoted text containing any letter is invalid and evaluates to
0. Because of this rule, all 3,750 scientific-notation exponents in the retail files (such as8.4208e-007, all1e-5or smaller) load as0. - Limits and comments: Each tag allows at most 64 arguments and
0x2800bytes of string data. The parser accepts//and/* */comments, though no retail.mapfile contains any.
2.1 Layout (the same order in all 210 files)¶
IMG "x.img";lines (257 total across the disc, up to 16 per map), followed byPCP "x.pcp";lines (222 total, up to 16 per map).PARTStemplates, followed by 2 blank lines.ACTIVE_LIGHT_SET, theLIGHT_SETblocks, and thenFLOOR,CHARA_POS,DEF_FOOT,TIME_FLAG,TIME_LIGHT_NUM, [TIME_CFADE],SKY_INFO, [LENS_FLARE], [ALL_SCISSOR], and [CHARA_LIGHT_ADJUST], followed by 1 blank line.MAP_PARTSplacements, followed by 2 blank lines.- [
CAMERA_INFOblock], followed by 2 blank lines. - [The map's own
FUNC_POINTblock], followed by 3 blank lines.
Blocks nest in a fixed order:
PARTS "name"; a template; nothing is drawn until placed
[FAR_CLIP distance,fade;]
LIGHT_FLAG no_light,no_plight;
[MOVE_FLAG a,b,c,d;]
PIECE "model.mds",show; repeated
PIECE_NAME "name";
PIECE_POS x,y,z;
PIECE_ROT x,y,z; radians
PIECE_SCALE x,y,z;
[PIECE_MATERIAL_START n; PIECE_MATERIAL "frame",material,r,g,b,a,int; ... PIECE_MATERIAL_END;]
[PIECE_COL_TYPE type[,int];]
PIECE_TIME start_hour,end_hour;
PIECE_END;
[FUNC_POINT n; ... FUNC_POINT_END;] points carried by every placement
PARTS_END;
MAP_PARTS "placement",show; places a copy of a template
[MAP_FAR_CLIP distance,fade;]
PARTS_NAME "template";
PARTS_GROUP "group";
PARTS_POS x,y,z;
PARTS_ROT x,y,z;
PARTS_SCALE x,y,z;
MAP_PARTS_END;
FUNC_POINT n; n = number of FUNC_DATA (the engine ignores it)
FUNC_DATA "kind",enable;
FUNC_NAME "name";
FUNC_FLAG a, b, start_hour,end_hour;
[FUNC_<KIND>_DATA ...;] one line, by kind (section 5)
FUNC_POS x,y,z, rx,ry,rz, sx,sy,sz;
FUNC_DATA_END;
FUNC_POINT_END;
2.2 Keywords (counts over the 210 files)¶
| Keyword | Count | Meaning |
|---|---|---|
PARTS |
10,751 | Part template definition |
FAR_CLIP |
7,261 (46 files) | Draw distance and fade range |
LIGHT_FLAG |
10,751 | Disables scene lights or point lights when drawing. (0,0) in 10,744 parts, (1,0) in 5, (0,1) in 2 |
MOVE_FLAG |
10,615 (missing from 136 parts in 13 files) | Bits 1/2/4/8: closed -X, -Z, +X, +Z sides of a dungeon cell (automap.hpp:58); read only by the dungeon generator |
PIECE |
65,744 | Model filename and show flag (0 in 1,046 pieces) |
PIECE_MATERIAL |
66 (44 blocks, 7 files) | Color override for one material on a specific frame node |
PIECE_COL_TYPE |
60,710 (missing from 5,034) | 0 = normal; non-zero pieces are not copied into placements (mapparts.cpp), so only the town editor uses them (the 118 Georama -h footprints) |
PIECE_TIME |
65,744 | Active visibility window from start_hour to end_hour; equal values mean always visible (685 pieces specify a time window) |
MAP_PARTS |
4,024 (176 files) | Template placement and show flag (0 in 76 placements) |
PARTS_GROUP |
4,024 (58 non-empty) | Visibility group name, toggled by fixed cameras |
CAMERA_INFO |
22 | Number of FIX_CAMERA blocks |
FIX_CAMERA |
35 | Fixed camera definition: FIX_CAMERA_POS, FIX_CAMERA_POS2 index,x,y,z, FIX_CAMERA_OFF_GROUP index,"group",int, FIX_CAMERA_RECT "box",min,max[,pos,rot,scale] |
FUNC_POINT |
5,933 | Trigger and function points (section 5) |
Environment settings (mapinfo.cpp:205-568)¶
| Keyword | Scope / Limit | Behavior |
|---|---|---|
LIGHT_SET n |
Up to 16 blocks | Defines one lighting and fog configuration |
FOV |
Inside LIGHT_SET |
Ignored by the engine; projection is always 52° (mapinfo.cpp:277) |
BGCOLOR, BGCOLOR2 |
Inside LIGHT_SET (0–255) |
Background clear colors. If BGCOLOR2 is 0,0,0, the engine copies BGCOLOR |
AMBIENT |
Inside LIGHT_SET |
Ambient light level (128 is neutral) |
LIGHT |
Up to 4 per LIGHT_SET |
LIGHT index,dx,dy,dz[,r,g,b] directional light |
PLIGHT |
Inside LIGHT_SET |
PLIGHT index,power,x,y,z,r,g,b point light |
FOG_ENABLE, FOG |
Inside LIGHT_SET |
FOG near,far[,r,g,b[,offset,far2]] fog range and color |
TIME_FLAG |
follow_clock,blend[,hour[,fixed]] |
When following the game clock, selects the active light set by hour and blends into the next set over the final hour of the band, with light 0 tracking the sun |
TIME_LIGHT_NUM |
N <= 8 (GetLightInfo bounds) |
4 uses fixed time bands; any other N divides the 24-hour day evenly starting from 9:00. When TIME_FLAG does not follow the clock, ACTIVE_LIGHT_SET selects the fixed light set |
SKY_INFO |
int,float[,sun_angle_degrees] |
Enables sky rendering and sun angle |
| Other setting tags | Map-level | FLOOR, CHARA_POS, DEF_FOOT, LENS_FLARE, TIME_CFADE, ALL_SCISSOR, and CHARA_LIGHT_ADJUST |
| Unused tags | Recognized by parser | LOD_START, LOD_BLEND, LOD_PIECE, LOD_END, and _MAP_INFO_TOP (never used on the disc) |
2.3 Writing a .map back byte for byte¶
A serializer that stores only parsed values (without retaining the original source text) can regenerate all 210 retail .map files byte-for-byte by following these eight rules:
- Encode text in Shift-JIS (
cp932); 16 files contain Japanese strings (such as"門"). - Use
LFline endings, include a trailingLF, emit no trailing spaces, and emit no comments. - Indent one tab per nesting level, except inside
LIGHT_SETbodies (which use one space) and onLIGHT_FLAGlines inside the 136PARTSblocks that lackMOVE_FLAG(which use no indent, produced by an older exporter). - Separate arguments with
,, except in four tags that insert a space at fixed positions:FUNC_FLAG a, b, c,dFUNC_POS p,p,p, r,r,r, s,s,sFUNC_INVENT_DATA id, ...FIX_CAMERA_RECT(after the name and between coordinate groups)
- Emit the exact number of blank lines after each section (
2,1,2,2,3; 10 blank lines in total per file), even when a section is empty. - Format floating-point numbers as C
%g(6 significant digits) with MSVC's 3-digit exponents (e-007), format whole numbers without a decimal point, and format negative zero as0. Do not write non-zero values that the engine must preserve using scientific notation, because the parser reads tokens containingeas0. - Track optional tags and variable argument counts per entry:
MOVE_FLAG,PIECE_COL_TYPE(1 or 2 arguments),FAR_CLIP,MAP_FAR_CLIP,TIME_FLAG(2 to 4 arguments),FOG(5 or 7 arguments),SKY_INFO(2 or 3 arguments),FUNC_FIRE_DATA(4 or 6 arguments),FUNC_ANIME_DATA(14 or 16 arguments),LENS_FLARE(omitted in 9 files),TIME_CFADE,ALL_SCISSOR, andCHARA_LIGHT_ADJUST(omitted in 12 files). - Compute the counts in
FUNC_POINT n,CAMERA_INFO n, andPIECE_MATERIAL_START ndirectly from the number of child entries, as they always match.
Retail anomalies to preserve when round-tripping:
- 10 files repeat a
PARTSname (the engine uses the first definition). - 2 files repeat a
MAP_PARTSname. - 2 files have gaps in
LIGHT_SETindices. - 532 pieces specify an empty model name
"". - About 490 pieces specify a model name that does not exist in any of the map's loaded packs (the engine skips drawing missing models).
3. Placement: templates, placements, pieces¶
- Templates and placements:
PARTSbuilds a template in memory (mapPARTS,mapload.cpp:538).MAP_PARTS_ENDcallsPlaceParts(name, pos, rot, scale)(mapload.cpp:970,map.cpp:313), which copies the matching template into the next free placement slot and applies the placement's name,showflag, far clip, and group. If the template name does not exist,PlacePartsignores the placement without consuming a slot. - Template-only maps: Across the disc, 176 maps place their templates in the
.mapfile; the other 34 maps contain only templates (dungeon floor libraries, add maps, and Georamag00) that the engine places at runtime.
Transforms¶
- World transform: Each vertex's world transform is
placement × piece × node_matrices. - Node local matrix:
T · Rz · Ry · Rx · S(mgCFrame::GetLocalMatrix,mg_frame.cpp:753), using right-handed rotations (mg_math.cpp:770-790) in radians (matching Blender'sXYZEuler order). - Axes and units: The
+Yaxis points up (gravity acts along-Y). A standard dungeon grid cell is 320 world units across. - Scale conventions: Scales of
-1, 1, 1(732 pieces, used for mirroring) and20, 20, 20(1,005 pieces) occur on the disc.
Models (info.cfg and pcpTYPE)¶
- Model lookup:
CMap::SearchMDS(map.cpp:245,mdslist.cpp:212) searches for a piece's model by name (case-insensitive) across every loaded model pack in the map and its add map. On the disc, 509 pieces reference a model from another map's pack, and maps frequently place the same mesh multiple times. - PCP
info.cfgformat: Starts withPCP_NAMEand listsMDS "name","source"; TYPE t; [FAR_CLIP]; MDS_END;. The model list size equals the pack's total.mdsand.chrcount, up to a maximum of0x1FF(CMdsList::LoadPCPFile,mdslist.cpp:484).
TYPE |
Engine Handler (pcpTYPE, mdslist.cpp) |
Pack Members | Placed Pieces |
|---|---|---|---|
0 |
Drawn model (mgLoadMDSFile) |
-m 7,646, other 240 |
37,318 |
1 |
Floor and wall collision (LoadCollisionFile) |
-a 2,673, Georama -h 122, -s 5, -k 3, other 36 |
13,910 |
2 |
Camera collision | -c 2,032, other 7 |
11,605 |
3, 4 |
Animated character (CreateChara), e.g. train engine kikan-m.chr |
.chr 67 |
928 |
- Collision suffixes: The
-asuffix stands for collision (atari, Japanese for a hit), not alpha.DrawSubskips oddTYPEvalues, so the engine never renders collision meshes. - Georama collision meshes: Georama towns also include
-hmeshes (edit-mode footprints with area kinds1,2,3, and5, partitioned byCEditCollision::Copy),-smeshes, and-kmeshes.
How scripts reference map objects¶
Map edits must preserve placement, piece, node, and trigger point names because scripts look them up at runtime:
| Map Object | Lookup Key | Script / Engine Functions | PAL Disc Usage |
|---|---|---|---|
| Placement | Slot index (MAP_PARTS order, add map first) or MAP_PARTS name |
GetPlaceParts (map.cpp:379-395), bind_handle_map_part |
5,700 of 6,304 bind_handle_map_part calls pass a placement name |
| Piece | PIECE_NAME |
set_map_part_motion (plays an animation on a .chr piece) |
202 calls to set_map_part_motion |
| Model frame | Node name | Frame lookup functions | Matched up to -- |
| Trigger point | FUNC_NAME (with part name "" for map-level points) |
set_func_point_enabled, bind_handle_func_point, get_func_point_pos, set_func_point_pos |
831 calls to set_func_point_enabled (552 with "") |
4. Meshes, textures, collision¶
4.1 Drawn meshes (-m)¶
- Geometry counts: 37,621 drawn meshes with 1,833,433 triangles, encoded as triangle strips (primitive types
0x4and0x104, 218k primitives) and triangle lists (types0x3and0x103, 49k primitives). - Hierarchy and limits: Node hierarchies reach up to 18 levels deep and include 35k non-identity node matrices, none of which have negative determinant (mirroring occurs at the piece level). Individual meshes contain up to 4,880 vertices and 57 materials.
- Node name uniqueness: In 1,488 of the 7,661
-mfiles, multiple nodes share the same base name before--(for example,grid54--f2appz0n1t-5_1andgrid54--f2appz0n1t-6_1), so only the full node name including flags uniquely identifies a node. - Lighting and vertex colors: Lighting is computed dynamically from the map's light sets (section 2.2) and point lights. Vertex colors represent painted color tints and alpha fades rather than baked lighting: 13,766 meshes contain vertex colors (covering 43% of
-mvertex corners), and most use only 1 or 2 distinct vertex colors (typically neutral grays178and119, with alpha255or0).
Node-name blend and render flags (mgSetFrameAttr, mg_dataset.cpp:163)¶
The suffix after -- on a node name controls its blend and render state (see models for the complete flag list). A material with diffuse alpha below 1.0 also enables alpha blending (0.5 in 441 materials).
| Flag / Suffix | Render Behavior |
|---|---|
aPP |
Additive blending |
aNN |
Subtractive blending |
aOF |
Forces opaque rendering |
aXX |
Sets the alpha-test threshold (XX) |
c0 |
Disables lighting (unlit) |
z0 |
Disables depth buffer writes |
fN |
Controls fog mode |
n1z0c0f2app- |
Common combination (722 nodes): additive and unlit |
a40aof- |
Common combination (362 nodes): alpha-tested and opaque |
4.2 Textures¶
- Registration and search path: The engine registers each
IMGfile named in the.mapwith the texture manager (CMap::LoadData,map.cpp:1505), and materials look up images by name across every loaded.imgfile. Across the disc, 44 maps reference more than oneIMGfile, and 9 maps reference more than onePCPfile. - Cross-pack references: Out of 3,828
(map, texture)references, 3,716 resolve to the map's own.imgfiles and 112 (across 35 maps) resolve to shared or paired map.imgfiles (such ascmn/g00/g00.ipk.d/a01.img). The texturenoIcondoes not exist anywhere on the disc. Consequently, a map exporter requires a search path of.imgfiles. - Animated textures and materials: 166
#texanimescripts across 161 map.imgfiles scroll and copy texture regions. In addition, 848FUNC_ANIME_DATApoints animate pieces and frames (section 5.1), and 44PIECE_MATERIALblocks recolor materials by name.
Texture wrap and clamp modes (GS CLAMP register)¶
Across the 549 map .img files (547 IM3 and 2 IM2), 52,791 UVs lie outside 0–1, confirming active texture tiling:
GS CLAMP Value |
Mode | Image Count (of 5,662) |
|---|---|---|
5 |
Clamp | 4,802 |
0 |
Repeat | 839 |
None (IM2) |
No CLAMP value |
18 |
| Other | Garbage values | 3 |
4.3 Collision (-a floor and wall, -c camera)¶
Floor and wall collision (-a) comprises 10,370 meshes and 294,135 triangles. Camera collision (-c) comprises 3,277 meshes and 59,649 triangles. Both use the standard MDS format and are loaded by LoadCollisionFile (collision.cpp, CreateCollisionMDT, verified in the assembly):
- Bounding boxes (
CColFrame): Each node becomes aCColFramecontaining its transform matrix and an axis-aligned bounding box computed at load time. The engine does not use a BSP tree, spatial grid, or precomputed bounding volume in the file. - Primitive format (
0x213): The loader reads only vertex positions and triangle lists with a corner stride of 1 (vertex index only). Any triangle strip, vertex-color-flagged (0x100) primitive, or primitive with normal/UV indices fails or is misread. Every collision primitive on the disc uses type0x213, except for 2 primitives of type0x13in-hfiles. - Material defaults: Collision materials are untextured except for 103 of 14,682 materials, and their remaining material fields hold default values (ambient
1, 1, 1, 0and specular power50).
Per-triangle attributes (encoded in material diffuse color)¶
Files store integer attribute k as k / 0.7, except ignore_mask, which is stored as 1 - k. An attribute value of 0 is stored as either 1.0 (the default white channel value) or 0.0:
| Diffuse Channel | Attribute | Engine Decode Formula | File Encoding Example | Values in -a Meshes and Behavior |
|---|---|---|---|---|
r |
ground |
(int)(r * 0.7 + 0.01) |
1.0 or 0.0 → 0 |
Almost always 0 |
g |
foot_sound |
(int)(g * 0.7 + 0.01) |
g = 2.8571 → 2 |
0–27; selects the footstep sound effect |
b |
area |
(int)(b * 0.7 + 0.01) |
b = 8.5714 → 6 |
Usually 6, 9, 5, 1, 7, or 8. Areas 1 and 7 represent water (GetCPolyAttr) |
a |
ignore_mask |
(int)(1 - a) |
a = -11 → 12 |
Usually 0, 12, 4, 8, or 255. Queries bitwise-AND their mask with ignore_mask (gameutil.cpp:1010) |
Collision query limits and checks¶
| Query Caller | Triangle Buffer Limit | Notes |
|---|---|---|
| Monsters and objects | 128 |
Keep collision meshes split across compact nodes so overlapping node counts stay within these limits |
Camera (MoveCamera, dng_main.cpp:2165-2187) |
512 |
Collects -c triangles within the distance to the player plus 10 units |
| Georama edit mode | 1024 |
Used during town editing |
- Player and NPC movement (
MoveCheck,gameutil.cpp:1599): Performs a raycast along the velocity vector,GetFootPolyextending 20 units downward, wall checks viaCheckWidth(radius15; a wall is any triangle withnormal.y < 0.5), and water level checks. - Hiding pieces from collision:
CMapPiece::GetPolyrequiresPIECE_COL_TYPEto be0(96 pieces setPIECE_COL_TYPEto1, which hides them from collision queries).
5. Trigger points (FUNC_POINT)¶
- Template vs. map-level points: Trigger points defined inside a
PARTStemplate are copied into each placement of that template (world = placement × FUNC_POS). Trigger points defined after theMAP_PARTSsection belong directly to the map (mapload.cpp:1147). - Transforms and default radii:
FUNC_POSstores position, rotation (in radians), and scale. Foreventpoints, the loader replaces any scale near1with a default interaction radius:15for doors,25for ladders, and20for chests (mapload.cpp:1437). - Active hours (
FUNC_FLAG): The last two numbers ofFUNC_FLAGspecify the active hours (CheckTime,funcpoint.cpp:19):start < enddefines a daytime window,start > endwraps past midnight, andstart == endis always active.
| Kind | Count | Data Line | Purpose and Behavior |
|---|---|---|---|
pos |
3,614 | None | Named positions that scripts and doors look up: point/pointN (3,439, inside door and entrance templates), kaifuku (136, recovery spots), npc_pos, and gcamp (camps) |
invent |
3,018 | FUNC_INVENT_DATA id, min xyz, max xyz, int, float, angle_degrees |
Photography subject: taking a photo whose line of sight hits the bounding box (min/max relative to the point's frame) awards invention idea id (< 1000 regular ideas; >= 1000 scoops). float sets maximum ray distance (400 when 0), and angle_degrees restricts camera angle relative to the point's back axis. Checked only on drawn placements (CMap::InScreenFunc, CMapParts::InScreenFunc); 1 map-level retail point can never be photographed |
event |
2,653 | FUNC_EVENT_DATA kind, event_no, program, 3 ints, target (15 chars), flags (action button, item, 0x100) |
Doors (1,250), events (1,157), treasure chests t_box (122), close_door, book, ed_door, and ladders lddr_b/lddr_t. program specifies the PROGRAM number to run in the map script |
flare |
2,631 | FUNC_FIRE_DATA r,g,b,draw[,int,int] |
Lens flares (an all-zero color defaults to 128, 90, 38) |
plight |
2,098 | FUNC_PLIGHT_DATA power, r,g,b (0-511), mode, 4 ints, flicker type, depth, period |
Point lights |
fire |
1,636 | FUNC_FIRE_DATA |
Fire effects |
effect |
1,234 | FUNC_EFFECT_NAME (an effect from the map's .efp) |
Particle and visual effects |
sound |
1,129 | FUNC_SOUND_DATA number, near, far, int, shape, start xyz, end xyz |
Ambient sound emitters |
anime |
848 | FUNC_ANIME_DATA "placement","piece","frame",drives,mode, start xyz, step xyz, end xyz[,uniform,relative] |
Per-frame animation of position, rotation, scale, color, or alpha on placements, pieces, and model nodes (section 5.1) |
- Point names vs. kinds: The strings
"talk","exit", and"branch"are point names (FUNC_NAME), not point kinds. - Extra
.cfgpoints and literal coordinates: A map's.cfgfile can add trigger points (FUNC_DATA "event"withFUNC_EVENT_DATA n,"check"). Scripts also frequently place characters and cameras using literal coordinates rather thanFUNC_POINTentries (for example,place_chara(13, 68.04, 41.85, 1180.61, 3.14)). - Doors (
CEditEvent,editevent.cpp): In Georama edit/town mode, when the player walks up to a door and presses the action button (flags[1, 0, 1]on every door on the disc; the third flag,0x100, fades the screen out), the engine plays the door-opening animation and sound effect:- If
program(the third number ofFUNC_EVENT_DATA) is greater than0, the engine runs that program in the map's script. - If
programis0, the engine enterstargetas an interior sub-map (using the same mechanism asgo_to_interior: a sub-map loaded alongside the town, sharing its 320 placement slots and texture blocks), or exits the interior whentargetis"exit".
- If
5.1 Animated pieces (FUNC_ANIME_DATA)¶
mapFUNC_ANIME_DATA (mapload.cpp:1257) reads the FUNC_ANIME_DATA line into CFuncPoint::AnimeData. One CObjAnime instance per point (include/funcpoint.hpp, where OBJ_ANIME_PARAM and OBJ_ANIME_MODE define the enum values below) runs the animation. The engine never reads the anime point's own FUNC_POS.
In ChronicleTwo, the CObjAnime implementation remains in assembly (funcpoint.cpp:51-55):
| Function / Symbol | Address | Purpose |
|---|---|---|
AssignFuncAnime |
0x2A10B0 |
Binds target object and applies initial start value at load time |
Step |
0x2A05D0 |
Per-frame update using jump table at_475__2 at 0x373650 |
SetParam |
0x2A0C20 |
Writes the animated property to the target placement, piece, or node |
GetParam |
0x2A0FD0 |
Reads the current property value |
CheckOver |
0x2A0530 |
Checks whether a moving axis has reached its target limit |
FUNC_ANIME_DATA arguments¶
Arguments 15 and 16 are optional (5 lines on the disc have only 14 arguments) and default to 0 (CFuncPoint::Initialize zeroes the structure).
| Argument | Field | Meaning |
|---|---|---|
| 1 | placement |
For a map-level point, the target placement's MAP_PARTS name (CMap::AssignFuncPoint, map.cpp:1365; GetPlaceParts, map.cpp:379, case-sensitive). For a point inside a PARTS template, the animation always targets the placement created from that template (CMapParts::AssignFuncAnime, mapparts.cpp:851, called by Copy during PlaceParts, map.cpp:313) and ignores this string (350 of 524 template points name the template, and 174 name something else or "") |
| 2 | piece |
Target piece within the placement, matched by PIECE_NAME (SearchPiece, mapparts.cpp:107, case-sensitive). "" animates the entire placement |
| 3 | frame |
Target node within the piece's model (mgCFrame::SearchFrame, mg_frame.cpp:980: depth-first search comparing names up to -- via StrCmp, mg_frame.cpp:948). "" animates the entire piece. When a node is found, the engine sets it to rotate around its own pivot (SetRotType(2)) |
| 4 | drives |
Property modified by SetParam (OBJ_ANIME_PARAM; see table below) |
| 5 | mode |
Per-frame update mode in Step (OBJ_ANIME_MODE; see table below); other values behave like mode 0 |
| 6–8 | start |
Initial (x, y, z) value |
| 9–11 | step |
Per-frame (x, y, z) delta; in mode 10, these three values represent start_hour, end_hour, and fade_hours |
| 12–14 | end |
Target/limit (x, y, z) value |
| 15 | uniform |
If non-zero, copies x into y and z for uniform scaling. Never set on the PAL disc |
| 16 | relative |
If non-zero with drives == 1, transforms the position delta through the piece's own matrix (CObject::GetMatrix, or the placement's matrix when piece is ""), so a piece with frame == "" advances by that vector every frame (acting as a velocity). Set on 40 lines on the disc, only 8 of which drive position (the battleship's two bobbing hulls in p01_battleship) |
drives values (OBJ_ANIME_PARAM)¶
drives |
Property | PAL Disc Count | Behavior and Modes Used |
|---|---|---|---|
1 |
Position | 66 | Writes (x, y, z) position. Modes: ping-pong 49, repeat 16, stop 1 |
2 |
Rotation (degrees) | 376 | Euler XYZ, clamped to ±360,000 and converted to radians. Modes: repeat 122, loop 119, ping-pong 72, stop 27, minute hand 14, hour hand 14, look 8 |
3 |
Scale | 199 | Writes (x, y, z) scale. Modes: ping-pong 162, random 33, stop 4 |
4 |
Vertex/node color | 202 | Node only: forces unlit rendering via mgCFrameAttr::no_light and writes color (128 per channel is neutral). Modes: ping-pong 173, random 23, repeat 6 |
5 |
Alpha | 5 | Node only: writes obj_alpha from the first component (1 is opaque). Modes: ping-pong 4, by the hour 1 (g03's seali, shown 20:00–6:00 fading over an hour) |
Other drives values modify nothing. Animated values are absolute in the coordinate space of the target object's parent and overwrite the object's static transform immediately. AssignFuncAnime applies start at load time, overriding a node's MDS transform, a piece's PIECE_POS/PIECE_ROT/PIECE_SCALE, or (from the first frame onward) a placement's MAP_PARTS transform. For rotations, start is an absolute Euler angle, not a relative offset.
mode values (OBJ_ANIME_MODE)¶
| Mode | Name | Per-Frame Behavior |
|---|---|---|
0 |
Hold | Writes the current value again (unused on the disc) |
1 |
Loop | Adds step indefinitely |
2 |
Stop | Adds step; once any moving axis reaches end, clamps and holds end |
3 |
Repeat | Adds step; once any moving axis reaches end, resets to start |
4 |
Ping-pong | Adds step until an axis reaches end (clamping to end), then subtracts step until an axis reaches start (clamping to start), repeating indefinitely |
5 |
There and back once | Same as mode 4 for one cycle, then stops permanently (unused on the disc) |
6 |
Look at the player | Rotation only: computes the yaw (y) and pitch (x) angles from the target object toward the player (in the placement's or node's coordinate space), clamped between start and end; z remains unchanged |
7 |
Random | Sets each axis independently to start + (end - start) * rand_0_to_1() |
8 |
Minute hand | Sets y = -360 * clock_hour (one full rotation per game hour); x and z remain unchanged |
9 |
Hour hand | Sets y = -30 * clock_hour (one full rotation per 12 game hours) |
10 |
By the hour | Evaluates to end during step[0]–step[1] hours (CheckTime), start outside that window, and blends linearly over step[2] hours before and after the window (SubTime, taking the shortest arc around the 24-hour clock) |
Runtime update rules and disc statistics¶
- Single-frame overshoot: If
stepovershoots the[start, end]range in a single frame, the value alternates betweenstartandendon every frame (used intentionally on nodesa_0toe_3ina05ia: scale0.9and0.8with step-1). - Per-frame update calls: Both the dungeon loop (
dng_main.cpp:1790) and the Georama edit loop (editloop.cpp:279, plus edit parts ateditmapeffect.cpp:85) callCMap::AnimeStep(map.cpp:1286) andCMapParts::AnimeStep(mapparts.cpp:773) once per frame while the point is enabled and within its active hours (CFuncPoint::Check,CheckTime), regardless of whether the target placement is currently visible. - Disabled points: Across the disc, 111
animepoints start disabled (scripts toggle them withset_func_point_enabled), and 4 specify active hours. A disabled point holds its last value. - Target breakdown: Across the PAL disc, 848
animepoints appear in 105 maps (524 inside templates and 324 at the map level). Of these, 783 animate a model node, 52 animate a whole piece, and 13 animate a whole placement (for example, the ground ins03, which scrolls 50 units per frame over 1,600 units and repeats). Twenty-eight points reference a placement or piece name that is absent from the.mapfile and therefore animate nothing.
6. Map kinds¶
| Category | PAL Disc Count | Description |
|---|---|---|
| Fixed scenes | 176 files (with MAP_PARTS placements) |
Towns and outdoor areas (s, m, f, a, z), interiors, dungeon boss and event rooms (d..b.., d..e..), special dungeon floors (d02f09, d04f09, d05f09, d05f10, d06f97–f99), and Georama base maps g01–g05 |
| Dungeon floor libraries | 28 files (d0Nf..) |
Contain PARTS templates only. Scripts call load_dungeon_map(map, room_cfg, flags), and CAutoMapGen::Build (automap.cpp:595) generates a fixed preset floor (0x40), a floor-indexed preset (0x2), or a random 20×16 (0x8) or 14×14 grid using dungeon/cfg_file/<cfg>.cfg. For each grid cell, the generator places one of 276 hardcoded template names (way00–51, room00–59, door00–99, part00–31, step00–31) at (x * 320, 0, y * 320), plus surrounding trees or mountains, geostone stand p01_gio, decorative stones obj01, and pots obj02 (see dungeons) |
| Add maps | 5 files (map/cmn) |
Shared template libraries loaded and placed by other maps: the train, trn2/s36, battleship01/02, and g00 (which holds the 52 Georama building parts) |
| Georama towns | g01–g05 |
Base map g0N.map loads together with g00's templates. g0N.cfg defines fixed parts (FIX_EPARTS), initial placements (INIT_EPARTS id,x,y,z,angle), and river pieces (EDIT_RIVER). g0N[0-6].gpi define editable Georama parts. Save data stores the placed layout (CEditData: up to 300 parts, rotation angles in 15° increments) |
Extra .cfg features and sky rendering¶
A map's .cfg file (CMap::LoadCfgFile) can add:
- Water surfaces:
WATER_VERTEXgrid between two corners, placed atWATER_POS. - Occlusion planes: Defined by four corner points.
- Draw-culling volumes (
DRAW_OFF_RECT): Parts inside the second bounding box are hidden whenever the camera is inside the first bounding box. - Extra trigger points:
FUNC_DATA "event"definitions. - Villager spawn positions:
NPC_PLACEandNPC_POS x, y, z, yaw.
When SKY_INFO enables the sky, CMapSky::DrawSky renders the sky around the camera using the map's .sky archive (or map/def.sky if the map has no .sky file). For each time band, it draws the sky and background sky models once normally above the horizon and once mirrored below the horizon.
7. What the engine needs of a new map¶
1. A row in the map table (map/map0.cfg–map6.cfg)¶
- At boot,
LoadMapName(mapselect.cpp) parsesmap/map<language>.cfgintoMapNameBuff(0x8000bytes). MAP_NAME_NUM nallocates the table (n + 1rows of0x1Cbytes each), and string data follows immediately after the table.- Each
MAP_NAMEstatement populates the next row without bounds checking, andGetMapNameInfolooks up only rows with index< n. - Adding a new map requires appending a
MAP_NAMErow at the end and incrementingn, which preserves existing map indices stored in save files (map_no) and scripts. All seven language tables (map0.cfg–map6.cfg) must assign the same row index. - The retail tables use 9,248 to 13,808 bytes (Korean), leaving room in
MapNameBufffor hundreds of new rows.
MAP_NAME Field |
Purpose |
|---|---|
add_path |
Optional add map loaded alongside the map |
type |
MapType in mapselect.hpp, read by the edit loop and menus (see table below) |
sel_type |
Category in the debug map select menu |
snd_id |
Sound set and default music ID (GetMapSndDataID) |
area_no |
Save file area ID for the last visited main map |
MapType |
Behavior |
|---|---|
1 |
Georama town with edit data |
2 |
Georama town interior, which runs g00's event script (GotoInterior, mapjump.cpp:524) |
3 |
Standard town or outdoor area |
4 |
Standard interior |
5 |
Future map (f01 to f04: disables the time board and world map, and uses its own area number) |
6 |
Future map interior |
7, 8 |
Dungeon loop maps |
2. Map files, transitions, and limits¶
- Map files at
GetMapPath(name)(section 1): Place the.mapfile and any optional.cfg,.mpk,.ipk,.efp, and.skyfiles of the same base name (GetLoadMapInfo,mapjump.cpp:147). The engine looks up pack members by the names listed in the.mapfile'sIMGandPCPlines, so a duplicated map can reuse another map's internal member names (such ase05.imgorm05_0.pcp). DATA.HD4and filename limits: Each new top-level file requires a record inDATA.HD4(12 bytes plus its null-terminated path; about 7.6 KB is free on the PAL disc, enough for 25 to 35 new maps of 4 to 6 files each). Engine filename buffers are 32 bytes long.- Save flags (
SAVE_MAP_FLAG_MAX): The save file tracks per-map flags (such as opened treasure chests) for map numbers below256. The retail disc uses 189 map numbers, leaving 67 slots that persist map flags; maps numbered256or higher load normally but do not save per-map flags. - Memory budgets: Keep file sizes within engine memory budgets (see memory).
- Map script loading (
LoadMapScript,mapjump.cpp): LoadsGetMapPath(name)+.stbviaLoadScript, which first tries<path>_<LanguageCode>.stband then falls back to<path>.stb(for example,map/m/m05/m05x_1.stbfor English, ormap/m/m05/m05x.stbif the language-specific file does not exist). Unnumbered retail scripts are compiled with Japanese strings. A map without a script loads with no events. When the map loads, the engine runsmap_start(100) unless the transition call specifies a different program (see running).
| Target Map Category | Script Transition Call | Notes |
|---|---|---|
| Georama town | go_to_edit_mode(number, program) |
Runs program when the map finishes loading |
| Standard map | jump_to_map(point, name_or_number, program) |
A door is an event point whose script program calls jump_to_map |
| Interior sub-map | go_to_interior(point, name) |
Shares the town's 320 placement slots |
| Dungeon map | load_dungeon_map(name) |
Loads a dungeon floor or boss map |