Merge branch 'model-docs'

Adds a manpage describing the model format.
This commit is contained in:
Epicalert 2021-03-31 15:44:19 +08:00
commit 6429ff82cd

131
docs/model-format.man Normal file
View file

@ -0,0 +1,131 @@
.TH FC2D_MODEL 5 "Facecam2D Model Format 0.3 Manual"
.
.SH NAME
fc2d_model \- Facecam2D model file format
.
.
.SH DESCRIPTION
Facecam2D uses
.B zip
archive files using the
.I .fma (Facecam2D model archive)
file extension, to store models.
.
These zip files contain a mandatory
.I toml
file called
.B model.toml,
which describes the model and its parts.
.
This file is called the
.B model descriptor.
.
Any model file that does not contain
.B model.toml
in the root of the archive is invalid.
.
.PP
Example
.B model.toml:
.
.sp
.
.EX
[format]
version_major = 0
version_minor = 3
[model_info]
name = "Example Model"
version = "1.0"
[[part]]
texture = "tex/head.png"
bind = "head"
[[part]]
bind = "head"
follow = "face"
factor = 0.75
[[textures]]
file = "tex/face-closedmouth.png"
[[textures]]
file = "tex/face-openmouth.png"
trigger = "mouth-open"
.EE
.
.PP
.
In addition to the model descriptor, the model archive can contain other
files (e.g. textures) that can be anywhere in the archive, including the root.
.
Unnecessary files should not be present in the archive, but archives with
unnecessary files are still valid.
.
.
.SH KEYS
.SS format
.TP
version_major
Integer: Major version of the model format (e.g. 0 for v0.3).
.
.TP
version_minor
Integer: Minor version of the model format (e.g. 3 for v0.3).
.
.
.SS model_info
.TP
name
String: The name of the model (will be displayed in the window title).
.
.TP
version
String: A version string for the model (currently unused).
.
.
.SS part
.TP
texture
String: Path to a texture file in the archive. Required if
.B [[textures]]
is not present in the part.
.
.TP
bind
String: A bind point which the part will be bound to.
Possible values: null, head, face
.
.TP
follow
String: A bind point which the part will follow depending on
.B factor.
The part will copy the position of
.B bind
but move in the direction of
.B follow.
.
.TP
factor
Float: How far the part will move towards the
.B follow
point.
If negative, the part will move in the opposite direction.
.
.SS textures
.TP
file
Path to a texture file in the archive. Required if
.B texture
is not present in the part.
.
.TP
trigger
A trigger that will cause the part to use this texture.
Possible values: null, mouth-open
.
.PP
When specifying multiple textures, the first one specified
will be used by default.