Model Metadata - voxraygames/worldbuilding GitHub Wiki

.vox (and .mbfb (brush)) files can come with a .json file that specified metadata about the model(s) contained in the file.

For example:

{
    object_type: "container",
}

Specifies that the model should represent a container when loaded into the game world.

You give these files a the same name as the corresponding model file, just with the extension replaced by .json. You can also place a literal .json file (no filename part, filename starts with .) in a directory, and this file will be loaded for ALL files in that directory that do not have their own metadata file.

Here are all the fields you can specify:

  • item_type: Default "Model" (an item which can be placed in the world), can also be one of "Armor" "Bag" "Boost" "Boot" "Gun" "Tool" "Resource" "Material" "Spell" etc.

    • If this is a model which is not directly intended to be handled by the player in gameplay (such as monster/npc models), make sure to set the type to "Sprite".
    • This is the "root type" of a model, it is important that you set this property correctly if the model is not intended to be a world object, as it avoids them being used incorrectly in gameplay or editing. Also, world objects use 4x as much GPU memory (for rotations) than sprites and other gameplay items.
    • If a Boost, you can optionally specify a sub-type, e.g. "Boost:Health" (which is the defaulty, or "Stamina" "Food", "Magic")
    • For Spell, subtypes are on https://github.com/aardappel/matvoxels/issues/141

  • object_type: a static world object if not set. Can be one of "container", "harvestable", "message", "trigger_src", "trigger_dst", "trigger_src_dst". This only applies when item_type is "Model".

  • auto_rotate: default false, specifies that this represent a bulk item where the rotation doesn't matter (such as a plant or rock), which means the editor will automatically rotate the model each time it is placed. this makes it easy to a more varied look when placing many of them.

  • bsm: a "block shader material" object, default value { spec_intensity: 0.3, emissive: 0.0 }. You can use this to influence the look of the model.

    • The emissive value makes the whole object emissive, and injects light into the world that bounces against nearby surfaces. This is separate from the emissiveness of individual voxel palette entries, which mostly brightens just those voxels and affects blooming. So you'll want to use one or the other depending on use case: For an object that is almost entirely emissive, use the object value, for an object which is mostly non-emissive but has emissive details, use palette entries. You may sometimes want to use both, e.g. some amount of object emissiveness with some additional palette emissiveness, for light sources.
    • volume_material can be set to 2 currently, which will make all voxels with the MagicaVoxel palette Index 1 be semi-transparent and rendereded as glass.

  • item_attrs ([int]): specifies the attributes for this item, which must correspond to the attr_definitions in code.

  • interact: a string indicating it should by default be associated with a certain kind of action/quest host, such as for vending machines etc. Something starting with workbench_ is a workbench, and its type is the rest of the string. Other strings trigger an action host, much like NPCs.

  • material (string): this overrides the equivalent settings that may have been specified in the filename / node name. The idea is that generally you want to specify this in the filename (or for a multi_ file in the MV node names) simply because every .vox needs a material and this avoids having to create a ton of .json files alongside them. But sometimes you want to change a material after the fact and can't change the filename anymore, so then this feature will be helpful. See Materials for gameplay for details on material assignment.

  • material_override: if you specify material, the file this is associated with will result in a single material, and the amount of material depends on the amount of solid blocks. Using material_override you can specify multiple materials, with an amount that is independent of its visual representation. For an example see mats/building/mult_props.json. The amount should be specified as an int where possible, but for items that are expected to be crafted in bulk (such as bullets) is allowed to be a float representing a smaller amount than 1. Since actual material usage will be in ints, it is important that for these items you specify default_amount, such that rounding doesn't make things unnecessarily expensive.

  • default_amount (int): specifies the amount of these items you get by default while crafting or buying/selling. Should be an amount such that when multiplied with material_override amounts and/or value you get whole numbers again.

  • item_override: In addition to material_override, require these items to craft this item. Specified as generator name + amount (int) each.

  • destroy: value 1..5 indicating the level of jackhammer required to destroy this item. Can be left unspecified (0), which means the level should be the max of all materials this object is made out of. For undestroyable use 10.

  • weight: Specify the weight that this model has. If not specified (on a model), it will be computed from material weights automatically. This is not meant to be a realistic weight: use what works for gameplay, though it is very roughly equivalent to kilos.

  • stack_size: Specify how many of this item can be stacked into a single slot in the inventory:

    • 0: automatically compute based on the number of blocks and their materials.
    • 1: big or heavy items: weapons, armors, large building pieces, trees.
    • 10: medium items: smaller building pieces such as wooden boxes, health packs
    • 25: small items: most foods.
    • 100: heavier materials/resources, such as metals. bullets.
    • 250: lighter materials.
    • 1000: very light things, such as coins.

    You can specify any integer, which will automatically be rounded to the closest stack category (just in case we ever change categories).

  • value: Specify the value (in coins a vendor will want to buy this item). If not specified (0.0) it will be computed from the value of materials. Use floats to allow to specify value of small things bought in quantities, but will be rounded up to integer coins by vendors.

  • uname: User facing name for use in the UI for models that can be an item in the inventory, e.g. Reenforced Leather Armor. If not set, will show the generic category name set by item_type, e.g. Armor.

  • sub: allows you to specify metadata for multi_ .vox files. Each element of this list corresponds to one sub element of the file, and you specify the sub_name property for each to see which you are talking about. See mats/building/mult_props.json for an example. Any property not set in this sub metadata will be "inherited" from the parent, so you can still set properties just once for the whole file, and optionally override them in the sub.

  • fpp and muzzlefpp: See any of the weapon models for an example.

  • behavior: The default behavior when this object is triggered. It must have object_type of trigger_dst or trigger_src_dst for this to have any effect.

  • num_slots: if this thing is a container, its number of slots. By default, this is 0, which means the player can take items out but not put them back in.

  • move_sound: Sound played when this object is moved between inventory/containers.

  • use_sound: Sound played when this object is used.

  • impact_sound: Sound played when object is shot with a gun. Only used for materials.

  • step_sound: Sound played when the local player walks on this material. Only valid if item_type is "Material".

  • alpha_multiplier: normally, any blocks "alpha" value gets computed by the amount of solid voxels in the block, and less than 10% solid voxels is considered "empty" for physics, raycasts and such. If this gives the wrong results for a model, the alpha can be artificially boosted (or reduced) to change the blocks in the model that count as solid.

  • ladder: (bool) functions as a ladder along the +X and -X directions (as seen in MagicaVoxel, but then can be rotated arbitrarily in game).

  • movable: (int) If non-zero, object can be moved with gloves of equivalent level. Zero means the object cannot be moved

  • explode: (object) e.g. { force: 1.0, max_material: 3 }.

  • sequence_mode: (int) when a file is not a multi_ file but does contain multiple objects, this flags specifies what that means:

    • 0 (default): this is an animation. should be 2..4 objects of the same size.
    • 1: these are variants of the same thing, can be any amount of objects of the same size. auto_rotate is implied, which in this case will cycle thru all the variants as you place them in the editor.

  • tileset: (string) a unique id that makes this particular model part of a "tileset". Read how to make Tilesets for more information.

  • repair_meta: (object)

    {
  model: string,                         // When repaired, this is the model that replaces the object.
  model_offset_nx: int = 0,              // What offset is needed when replacing the model in the -x direction.
  model_offset_ny: int = 0,              // What offset is needed when replacing the model in the -y direction.
  model_offset_nz: int = 0,              // What offset is needed when replacing the model in the -z direction.
  model_offset_px: int = 0,              // What offset is needed when replacing the model in the +x direction.
  model_offset_py: int = 0,              // What offset is needed when replacing the model in the +y direction.
  required_materials: [MaterialAmount],  // Which materials are required to repair, e.g. { name: "wood", amount: 5 }
  required_resources: [ResourceAmount],  // Which resources/items are required to repair, e.g. { name: "mdl/basic_chest", amount: 1 }
}

  • container: (optional object)

      {
    open_model: string,         // When container is emptied, which model to replace it with.
    closed_model: string,       // When placing an object in an empty container, which model to replace the container with.
    model_offset_nx: int = 0,   // Model offset, specified in the same way as in `repair_meta` above.
    model_offset_ny: int = 0,
    model_offset_nz: int = 0,
    model_offset_px: int = 0,
    model_offset_py: int = 0,
  }

  • default_tag: (string) if set, this object will be tagged with the given tag, even when placed in the game.

  • workbench: (string) one of player wood stone iron smelter stove campfire magic. This determines the workbench the item will be crafted on if turned into a blueprint.

  • respawn: (optional object)

      {
      inactive_model: string,  // Which model to use when the respawn object is inactive.
      active_model: string,  // Which model to use when the respawn object is active.
  }

  • connected: (string) if set, some combination of "-X+X-Y+Y-Z+Z", e.g. "-X+Z". Represents how this object should connect to other objects (for the purposes of determining whether objects should fall)

  • inhibit_falling: (bool) if true, this object won't fall and won't cause other objects nearby to fall when added/removed.

You should generally only specify fields that are not at their default values.

mats/building/multi_props.json:

{
    sub: [
        {
            sub_name: "garbage_4_chest_6",  // Futuristic crate.
            is_container: true,
            // Specify a specific set of materials this drops/requires, instead of relying on block count.
            material_override: [
                { name: "steel", amount: 10 },
                { name: "glass", amount: 1 },
            ]
        },
        {
            sub_name: "garbage_4_chest_7",  // regular metal barrel.
            material: "steel",  // Override the "garbage" in the name, amount is 8, since its 2x2x2 blocks.
        },
    ]
}

Making items craftable in-game

Giving an item the right stats using the above properties to craft it does not automatically make it available for crafting in-game. A level designer decides what each workbench may craft for each world independently, see also Action Editor. There are however presets of sets of items that you can easily load in Action Editor that many worlds will use as-is, and what is available in those is currently specified in actions.lobster, see the Craftables actions.