Modeling

Importing Models

Importing 3D models is done using the "Model" configuration function. Models will be loaded from the models/ folder. Supported formats are .obj, .gltf, and .glb.

Parameters:

filename|instance|flip||actions,bones,textures|projectionfix

When providing the file name, remember to include the file extension.

The instance parameter controls whether or not to use instancing (a more efficient way to render multiple copies of the same model).
Values are true, false, or clone (to use cloning instead of instancing).
The default optimization method is settable in the plugin parameters.

The flip parameter can be used to flip the model's geometry. This parameter exists for backwards compatibility with models created for an older version of MZ3D.

The actions parameter modifies information about the model's animations. This parameter is a nested parameter list, so it should be wrapped in {}.
You should provide a list of named arguments, with the name being the name of the action and each argument being another nested parameter list with the following parameters:

alias,speed

Alias is a new name for the action. For example, if you change the name to "walk", it will be used as the walking action.
Speed can be used to speed the animation up or slow it down. The default speed is 1.
Example: model(char.glb,actions:{sprint:{alias:run,speed:1.4},stand:{alias:idle}})

The bones parameter is used to modify the model's bones. This parameter is a nested parameter list, so it should be wrapped in {}.
You should provide a list of named arguments, with the name being the name of the bone and each argument being another nested parameter list with the following parameters:

scale

Scale is the new scale for the bone. Example: model(char.glb,bones:{head:{scale:0.5}})

The textures parameter is used to replace the textures used in an imported model. This parameter is a nested parameter list, so it should be wrapped in {}.
Each argument is an additional nested parameter list with texture parameters.
If the model has multiple textures, you can provide a list of texture parameter lists.

Example:

model(char.glb, textures:{ {./img/characters/Actor1.png,75%,50%,100%,100%} })

The projectionfix parameter sets whether the model's projection should be adjusted for the 2D camera mode. If true, the model will avoid being stretched vertically. Objects that are part of the environment should have projectionfix:false and characters should have projectionfix:true.

.obj

When using .obj format, there should also be a .mtl file which describes the model's materials.
.obj and .mtl files are plain text, so you can open them in a text editor.

The "mtllib" line in the .obj file points to the location of the .mtl file.

The .mtl file will have lines that start with "map_" such as "map_Kd" and "map_Bump" which point to the texture files.

Ensure that all file paths are relative paths. You should have no paths that start with "C:\", or the model won't work when loaded on someone else's computer because the files will be in different locations.

For example, to load a texture from an image in the tilesets folder: map_Kd ../img/tilesets/Inside_C.png

.obj models only support static meshes. If you need to animate the model, you should use .glb or .gltf format instead.

.glb

.glb files are self-contained and contain the model, materials, and textures all in one file.
They are the easiest to work with because there are no external files to worry about.

.gltf

.gltf files are the same format as .glb files, but stored as a text file instead of a binary file.
Unlike glb, it's possible for a gltf file to reference external files, so you may need to include the textures and other files it references. Again, you should also ensure that all file paths used in the .gltf file are relative paths.

.glb and .gltf files support animation. To run one of the model's animations, use the Action Command.

Actions named "idle", "walk", "run", "jump", "fall", "swim", or "swimmove" will be used as default actions depending on the character state.

Mesh Building

The "Mesh" configuration function is used to construct a mesh for the character based on a mesh string. Mesh strings are a special format created specifically for MZ3D that contain instructions for building a mesh.

Using mesh strings might seem a bit more complicated than importing 3D models, but it allows you to define meshes directly in plain text (such as in a texture .json file).

A mesh string is composed by a series of mesh parts, each of which is a letter (or series of letters) which determines what type of part it is, followed by a nested parameter list.

The following mesh part types are available:

c - cuboid

Defines a cuboid.
Parameters:

xsize,ysize,zsize|xoff,yoff,zoff|yaw,pitch,roll|texture:top,bottom,south,east,north,west

Example (shelf mesh):

mesh(c{1,.5,1.5|0,-.25,0||{+0,+-1,1,25px},{0},{+0,+-23px,1,71px},{B,7,22+22px,1,-70px}})

q - quad

Defines a quad.
Parameters:

xsize,ysize|xoff,yoff,zoff|yaw,pitch,roll|texture

Example (tree):

mesh(
qq{1,2|,,1|,90|{B,5,19,1,2}}
qq{1,2|,,1|90,90|{B,5,19,1,2}}
q{1,1|,,.75||{B,6,20}}
q{1,1|,,1.25||{B,6,20}}
)

p - points

Defines a mesh using point data.
Parameters:

positions...|indices...|uvs...|texture

Example:

mesh(p{0,0,0, 0,-1,.5, .866,.5,.5, -.866,.5,.5, 0,0,1|0,1,2, 0,3,1, 0,2,3, 4,3,2, 4,2,1, 4,1,3|.5,.5, .5,0, .75,.75, .25,.75, .5,.5|{A5,6,8}})

I have made a Blender Add-On for converting models into mesh strings of this type.

To make a double-sided shape, you can repeat the letter for the mesh part type twice ("cc", "qq", or "pp").

You can mix different part types in the same mesh string.

Example (chair):

mesh(c{.75,.6,.25|0,-.075,0||{+0,+10px,48px,17px},{0},{+0,+27px,1,13px}}
c{.125,.65,.125|-.3375,-.075,.25||{+0,+4px,7px,22px},{0},{+0,+26px,7px,5px},{+7px,+31px,34px,6px},{+0,+26px,7px,5px},{+7px,+31px,34px,6px}}
c{.125,.65,.125|.3375,-.075,.25||{+41px,+4px,7px,22px},{0},{+41px,+26px,7px,5px},{+7px,+31px,34px,6px},{+41px,+26px,7px,5px},{+7px,+31px,34px,6px}}
c{.125,.125,.875|-.3375,-.3375,.375||{+0,+-45px,7px,7px},{0},{+0,+-38px,7px,42px}}
c{.125,.125,.875|.3375,-.3375,.375||{+41px,+-45px,7px,7px},{0},{+41px,+-38px,7px,42px}}
qq{.55,1|0,-.3375,.75|0,90,0|{+7px,+-45px,34px,55px}}
)