diff --git a/docs/model-format.man b/docs/model-format.man new file mode 100644 index 0000000..2e166f5 --- /dev/null +++ b/docs/model-format.man @@ -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.