This is a centralized place for the documentation and other discoveries about the internal working of Kingdom Hearts games.

View on GitHub

OpenKh Tool Documentation - MapGen



MapGen is a tool to create .map file from 3D model data.

Command usage

OpenKh.Command.MapGen.exe -h

Usage: OpenKh.Command.MapGen [options] <InputFile> <OutputMap>

  InputFile     Input file: mapdef.yml or model.{fbx,dae}
  OutputMap     Output map file

  --version     Show version information
  -?|-h|--help  Show help information

Supported 3D model data formats

MapGen utilizes Assimp (Open Asset Import Library) to import 3D model data.

Thus Assimp supported formats will be usable.

See also:

Supported 3D model data concepts

Example: fbx to map

Command line:

OpenKh.Command.MapGen.exe terrain.fbx


DEBUG ymlFile is "H:\Proj\khkh_xldM\newMap\terrain\mapdef.yml"
DEBUG baseDir is "H:\Proj\khkh_xldM\newMap\terrain"
DEBUG Loading 3D model file "H:\Proj\khkh_xldM\newMap\terrain\terrain.fbx" using Assimp.
DEBUG Starting triangle strip conversion for 1 meshes.
DEBUG Mesh: Plane (256 faces, 1,024 vertices)
DEBUG Output: 289 vertices, 36 triangle strips.
DEBUG The conversion has done.
DEBUG Starting mesh splitter and vif packets builder.
DEBUG Output: 10 vif packets.
DEBUG The builder has done.
DEBUG Starting vifPacketRenderingGroup builder.
DEBUG Output: 1 groups.
DEBUG Going to load material "geo".
DEBUG Load image from "H:\Proj\khkh_xldM\newMap\terrain\images\geo.imd"
DEBUG Building map file structure.
DEBUG Writing to "H:\Proj\khkh_xldM\newMap\terrain\".


3D model data cannot hold all of extra data needed for map conversion. Thus write mapdef.yml file as needed, and place it to the same folder having 3D model data.

Material definition

# Declare supplemental info per material of any associated meshes in 3D model data
# Pattern matching to hit a material. It ignores case.
# Accept like: `*clip`, `*old*`, `material???`
# It respects only first matched material. If there are 2 or more hits, later ones will be ignored.
- name: '*'
  fromFile: 'floor.imd'

# This never reach.
- name: 'ceil'
  fromFile: 'ceil.imd'


# Apply xyz uniform scale to every mesh vertex. Skipped if applyMatrix exists.
scale: 1


# Apply matrix for each input vertex position.
# Default is null and assume identity matrix.
applyMatrix: [
    1, 0, 0, 0, 
    0,-1, 0, 0, 
    0, 0,-1, 0, 
    0, 0, 0, 1

# This matrix is useful for maps exported from KH1.


# Specify parent directory path to image files that can be used by `fromFile`
# The path accepts both absolute path, and relative path from folder having `mapdef.yml`.
# Default is `images`. If you define imageDirs, The default `images` will be lost.
- 'images'
- 'images2'
- 'images3'


OpenKh.Command.ImgTool.exe will be used if .png file is passed to fromFile.

# Apply globally
imgtoolOptions: '-b 8'

# Apply to specific material, and override global settings.
- name: `floor`
  imgtoolOptions: '-b 8 -p'


# Apply textureOptions globally. The individual property of textureOptions will be adopted.
  # addressU
  # addressV are one of: 'Repeat', 'Clamp', 'RegionClamp', 'RegionRepeat'
  addressU: 'Repeat'
  addressV: 'Repeat'

# Apply to specific material. This overrides global setting.
- name: `floor`
    addressU: 'Repeat'
    addressV: 'Repeat'


# Values to use to control the speed of horizontal and vertical UV scrolling.
# Mapgen doesn't seem to append these values, so they'll need to be added manually.
# Additionally, looping will need to be fixed in the GSInfo portion of the texture that has UV Scrolling.
# The 129th-132nd bytes in that texture control this.
  - index: 0
    u: 64000000
    v: 64000000


# Disable triangleStrips optimization. Every output shape becomes triangle.
disableTriangleStripsOptimization: true


# Disable BSP collision builder. Compose single huge collision table.
disableBSPCollisionBuilder: true


# The mesh having this material is skipped.
- name: 'Material'
  ignore: true


# The mesh having this material is not rendered.
# But collision plane is generated.
- name: 'clip'
  nodraw: true


# The mesh having this material is rendered.
# But collision plane is not generated.
- name: 'falsewall'
  noclip: true


# Specify one image file for this material.
# It uses material name as part of file name if omitted.
# For `floor`:
# - `floor.imd`
# - `floor.png`
- name: 'floor'
  fromFile: 'floor_texture.imd'


# Specify `surfaceFlags` to this material.
# `0x3f1` is one of floor representation.
# This value is made up of 4 bitflags.
# They control things like whether Inverse Kinematics should apply, if a player can grab the ledge, etc.
# Grabbable Ledges should only be placed on top of surfaces, some buggier interactions with ledges may occur otherwise.
- name: 'floor'
  surfaceFlags: 0x3f1

Bit 1

Kind: 0x1, 0x2, 0x3, 0x4, may go up to 0x0F?
Hit_Player: 0x10
Hit_Enemy: 0x20
Hit_Flyenemy: 0x40
Hit_Attack: 0x80

Bit 2

Hit_Safety: 0x1
IK: 0x2
Grabbable Ledge: 0x4
Barrier: 0x8
MSG_Wall: 0x10
Callback: 0x20
Carrib_Disp: 0x40 or 0x80

Bit 3 (Unknown uses an additional one?)

Belt: 0x1
Polygon_SE: 0x2 or 0x4
Hit_RTN: 0x8
Nohit_Floor: 0x10
Unk: 0x20, 0x40, 0x60, 0x80, 0xA0, 0xC0, 0xE0, 0x100, 0x120, 0x140, 0x160


maxColorIntensity: from 0 to 255

# Set maxColorIntensity globally.
maxColorIntensity: 128

# Specify maxColorIntensity to the material for overriding global settings.
# Apply max value to each RGB color component of vertex color.
- name: 'floor'
  maxColorIntensity: 128


maxAlpha: from 0 to 255

# Set maxAlpha globally.
maxAlpha: 128

# Specify maxAlpha to the material for overriding global settings.
# Apply max value to each Alpha color component of vertex color.
- name: 'floor'
  maxAlpha: 128


# Specify maxIntensity to this material.
# Set `transparentFlag: 1` to use transparency texture.
- name: 'five'
  transparentFlag: 0


# Specify true if you want to skip png to imd conversion.
skipConversionIfExists: true


# Specify true if you want to reuse `.imd` file converted by ImgTool.
# This is useful if diffuse texture file path is `images/tex.png`, and omit re-conversion.
reuseImd: true


# Index of UV Scrolling values to use.
# These are found at the end of the texture file.
# "_KN5" denotes the end of the number of entries.
- name: 'six'
  uvscIndex: 0


Ground value in collision. </br> These values are used to determine which footsteps to play when walking or running across the collision with that materials name. </br> Most sound effects will not play without modifying for that rooms world.</br> PAX like water splashes and footprints also depend on the collision having specific values. </br> For light collision, this is index to onColorTable[].

- name: 'floor'
  ground: 1

What each value corresponds to is shown below.

1: Stone
2: Stone_SP
3: Dirt*
4: Dirt_SP
5: Sand
6: Sand_SP
7: Wood
8: Board
9: Creakwood
10: Lawn*
11: Grass
12: Drygrass
13: Water*
14: Deepwater
15: Snow*
16: Metal
17: Ironwire
18: Carpet
19: Cloth
20: Sofa
21: Roof
22: Roof_SP
23: Electric
24: Electric_SP
25: Glass
26: Rubber
27: Bone
28: Paper
29: Fragment
30: Last
*This will play PAX Effects if available.


FloorLevel value in collision

- name: 'floor'
  floorLevel: 1


Setting cameraClip to true will generate camera collision plane.

- name: 'camera'
  nodraw: true
  noclip: true
  cameraClip: true
  cameraFlags: 0x000003F0


This is Collision.Attributes (surfaceFlags) of camera collision data.

- name: 'camera'
  nodraw: true
  noclip: true
  cameraClip: true
  cameraFlags: 0x000003F0


Setting lightClip to true will generate light collision plane.

- name: 'light'
  nodraw: true
  noclip: true
  lightClip: true
  lightFlags: 0x000803F1


This is Collision.Attributes (surfaceFlags) of light collision data.

- name: 'light'
  nodraw: true
  noclip: true
  lightClip: true
  lightFlags: 0x000803F1


- name: 'floor'
  noShadow: true


- name: 'floor'
  alphaAdd: true


- name: 'floor'
  alphaSubtract: true


Set IsSpecular to true, and then attach normal vector.

- name: 'lens_flare'
  normal: true


# Customize output bar entries for output `.map` file.
# toFile is option in case of needs to save raw data individually.
    name: "MAP"
    toFile: 'MAP_0.model'
    name: "MAP"
    toFile: 'MAP_0.modeltexture'
    name: "ID_e"
    toFile: 'ID_e_0.coct'
    name: "eh_1"
    toFile: 'eh_1_0.doct'
    name: "CH_e"
    toFile: 'CH_e.coct'
    name: "COL_"
    toFile: 'COL_.coct'


Applying nococt: true will skip COCT generation. default is nococt: false.

nococt: true

This is a mandatory option if we build SK0 model, because the bounding box of COCT has limitation of INT16 range (-32768 ~ 32767).


Applying nodoct: true will skip DOCT generation. default is nodoct: false.

nodoct: true

This is a mandatory option if we build SK0 model, because the bounding box of DOCT has limitation of INT16 range (-32768 ~ 32767).


Split nodes until single node has up to specified mesh face count.

collisionPartitionSize: 300


Split nodes until single node has up to specified mesh face count.

doctPartitionSize: 500


Fog effect. Color is AABBGGRR format.

  color: 0x80402010
  min: 100
  max: 700
  near: 0
  far: 255


Background color in AABBGGRR format.

bgColor: 0x80804010


Map colors up to 16 colors. 0x80808080 are appended on lack. Excess is dropped. Color is in AABBGGRR format.

  - 0x80808080
  - 0x80808080
  - 0x80808080


# This is default declaration of each material.
# And also this is used for fallback purpose.
- name: 'fallbackMaterial'
  ignore: false
  fromFile: null
  fromFile2: null
  noclip: false
  nodraw: false
  surfaceFlags: 0x3f1
  maxColorIntensity: null
  maxAlpha: null
  imgtoolOptions: null
    addressU: null
    addressV: null

imageDirs and fromFile

You can specify imageDirs like:

- 'images'
- 'images2'
- 'images3'

The image file associated with material will be located in this rule:





Example of designer tools usage