File name remapping - voxraygames/worldbuilding GitHub Wiki

World files (and brush files, and savegame files..) refer to voxel model files by name, so typically, once a voxel file is used in one or more levels, renaming voxel files can cause loading world files to fail, and should be avoided.

To allow safe renaming where it is necessary, we currently have mats/generator_mappings.json which is a centralized file where voxel resources can be moved without affecting existing worlds. Example:

{
    single_mappings: [
        { src: "objects/lights/garbage_4_light_lantern", dst: "objects/lights/iron_4_light_lantern" }
    ],
    multi_mappings: [
    ]
}

This changes the name of the file (in this case, the different material could have also been achieved with metadata).

• Names are specified as "generator names", meaning they are omit the leading mats/ part of the path and the .vox extension, and may include a sub-model reference (e.g. dir/myvox:mynodename) where mynodename refers to the name of a model inside the file.

• When a worldfile loads that refers to the old (src) it will now load the dst. The name is replaced entirely: If the world containing this reference is saved again after the mapping was added, it will now refer to the new name only.

• This means that for quick fixes, or fixes that for sure only affect one file, these entries do not need to be added to src/generator_mappings.json permanently, but in case of doubt where it is not known how many files may refer to this file, it is better to add it.

• You may also change the path as part of the rename.

• You can use this to merge multiple copies of something into one.

• single_mappings is used to map single generators onto others, and multi_mappings is used for mapping whole files that contain multiple models (that start with multi_, see Materials for gameplay). For example, mapping { src: "landscape/desert", dst: "landscape/prairie" } will remap ALL generators like landscape/desert:submodelname.

• You typically must replace with something of the same type, with exceptions:

  • You may change from sub-model to a regular stand-alone model and vice versa, i.e. can be used to split up a multi_ file into smaller parts, or merge into one.
  • If changing to a different voxel model, you typically want to change to a voxel model of the same size, though size changes will typically work in most cases.
  • You currently cannot replace brushes by vox models or vice versa.

• Since these are generator names, not necessarily file names:

  • You currently cannot rename entire directories at once, this can possibly be supported in the future.

• For programmers: these single_mappings work for anything addressed over add_model and add_model_sub, including saved items etc. The multi_mappings specifically work for add_model_sub when it loads the parent multi file it is part of, and any other directly loaders of multi files such as the animation system.