OpenKh Tool Documentation - MapGen
TOC
- Overview
- Command usage
- mapdef.yml
- Material definition
- scale
- applyMatrix
- imageDirs
- imgtoolOptions
- textureOptions
- uvscList
- disableTriangleStripsOptimization
- disableBSPCollisionBuilder
- ignore
- nodraw
- noclip
- fromFile
- surfaceFlags
- maxColorIntensity
- maxAlpha
- transparentFlag
- skipConversionIfExists
- reuseImd
- uvscIndex
- ground
- floorLevel
- cameraClip
- cameraFlags
- lightClip
- lightFlags
- noShadow
- alphaAdd
- alphaSubtract
- normal
- bar
- nococt
- nodoct
- collisionPartitionSize
- doctPartitionSize
- fog
- bgColor
- onColorTable
- default
- imageDirs and fromFile
- Example of designer tools usage
Overview
MapGen is a tool to create .map
file from 3D model data.
Command usage
OpenKh.Command.MapGen.exe -h
1.0.0
Usage: OpenKh.Command.MapGen [options] <InputFile> <OutputMap>
Arguments:
InputFile Input file: mapdef.yml or model.{fbx,dae}
OutputMap Output map file
Options:
--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: https://github.com/assimp/assimp/blob/master/doc/Fileformats.md
Supported 3D model data concepts
- Mesh
- Face (vertex indices)
- Vertex position (x, y, z)
- Vertex UV component (s, t)
- Vertex color (r, g, b, a)
- Material name
- Material’s diffuse texture file path
Example: fbx to map
Command line:
OpenKh.Command.MapGen.exe terrain.fbx
Output:
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\terrain.map".
DEBUG Done
mapdef.yml
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
materials:
# 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'
scale
# Apply xyz uniform scale to every mesh vertex. Skipped if applyMatrix exists.
scale: 1
applyMatrix
# 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.
imageDirs
# 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.
imageDirs:
- 'images'
- 'images2'
- 'images3'
imgtoolOptions
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'
textureOptions
# Apply textureOptions globally. The individual property of textureOptions will be adopted.
textureOptions:
# addressU
# addressV are one of: 'Repeat', 'Clamp', 'RegionClamp', 'RegionRepeat'
addressU: 'Repeat'
addressV: 'Repeat'
# Apply to specific material. This overrides global setting.
- name: `floor`
textureOptions:
addressU: 'Repeat'
addressV: 'Repeat'
uvscList
uvscList:
- index: 0
u: 64000000
v: 64000000
disableTriangleStripsOptimization
# Disable triangleStrips optimization. Every output shape becomes triangle.
disableTriangleStripsOptimization: true
disableBSPCollisionBuilder
# Disable BSP collision builder. Compose single huge collision table.
disableBSPCollisionBuilder: true
ignore
# The mesh having this material is skipped.
- name: 'Material'
ignore: true
nodraw
# The mesh having this material is not rendered.
# But collision plane is generated.
- name: 'clip'
nodraw: true
noclip
# The mesh having this material is rendered.
# But collision plane is not generated.
- name: 'falsewall'
noclip: true
fromFile
# 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'
surfaceFlags
# Specify `surfaceFlags` to this material.
# `0x3f1` is one of floor representation.
- name: 'floor'
surfaceFlags: 0x3f1
maxColorIntensity
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
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
transparentFlag
# Specify maxIntensity to this material.
# Set `transparentFlag: 1` to use transparency texture.
- name: 'five'
transparentFlag: 0
skipConversionIfExists
# Specify true if you want to skip png to imd conversion.
skipConversionIfExists: true
reuseImd
# 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
uvscIndex
- name: 'six'
uvscIndex: 0
ground
Ground value in collision. Such as 30, 25, 8, 2, 1, or 0
For light collision, this is index to onColorTable[]
.
- name: 'floor'
ground: 1
floorLevel
FloorLevel value in collision
- name: 'floor'
floorLevel: 1
cameraClip
Setting cameraClip to true will generate camera collision plane.
- name: 'camera'
nodraw: true
noclip: true
cameraClip: true
cameraFlags: 0x000003F0
cameraFlags
This is Collision.Attributes (surfaceFlags) of camera collision data.
- name: 'camera'
nodraw: true
noclip: true
cameraClip: true
cameraFlags: 0x000003F0
lightClip
Setting lightClip to true will generate light collision plane.
- name: 'light'
nodraw: true
noclip: true
lightClip: true
lightFlags: 0x000803F1
lightFlags
This is Collision.Attributes (surfaceFlags) of light collision data.
- name: 'light'
nodraw: true
noclip: true
lightClip: true
lightFlags: 0x000803F1
noShadow
- name: 'floor'
noShadow: true
alphaAdd
- name: 'floor'
alphaAdd: true
alphaSubtract
- name: 'floor'
alphaSubtract: true
normal
Set IsSpecular
to true, and then attach normal vector.
- name: 'lens_flare'
normal: true
bar
# Customize output bar entries for output `.map` file.
# toFile is option in case of needs to save raw data individually.
bar:
model:
name: "MAP"
toFile: 'MAP_0.model'
texture:
name: "MAP"
toFile: 'MAP_0.modeltexture'
coct:
name: "ID_e"
toFile: 'ID_e_0.coct'
doct:
name: "eh_1"
toFile: 'eh_1_0.doct'
camera:
name: "CH_e"
toFile: 'CH_e.coct'
light:
name: "COL_"
toFile: 'COL_.coct'
nococt
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).
nodoct
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).
collisionPartitionSize
Split nodes until single node has up to specified mesh face count.
collisionPartitionSize: 300
doctPartitionSize
Split nodes until single node has up to specified mesh face count.
doctPartitionSize: 500
fog
Fog effect. Color is AABBGGRR format.
fog:
color: 0x80402010
min: 100
max: 700
near: 0
far: 255
bgColor
Background color in AABBGGRR format.
bgColor: 0x80804010
onColorTable
Map colors up to 16 colors. 0x80808080
are appended on lack. Excess is dropped. Color is in AABBGGRR format.
onColorTable:
- 0x80808080
- 0x80808080
- 0x80808080
default
# 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
textureOptions:
addressU: null
addressV: null
imageDirs and fromFile
You can specify imageDirs like:
imageDirs:
- 'images'
- 'images2'
- 'images3'
The image file associated with material will be located in this rule:
{baseDir}/{eachInputDir}/{eachFileName}
baseDir:
- The folder having
mapdef.yml
file.
eachInputDir:
images
(fromimageDirs:
section)images2
(fromimageDirs:
section)images3
(fromimageDirs:
section)- The folder having
mapdef.yml
file.
eachFileName:
fromFile
of material (you can specify)fromFile2
of material (extracted from material’s diffuse texture file path as imd extension, if reuseImd set)fromFile3
of material (extracted from material’s diffuse texture file path)- material name + “.imd”
- material name + “.png”
Example of designer tools usage
- Design a full map model data with Blender,
and then export entire world to
.fbx
file format.
Note : The Y coordinate is up vector in KH2.