File Mapping

File mapping defines how files in your modules are exported to the final addon structure. ModularMC provides several ways to specify target paths, from simple string paths to automatic path generation.

Basic String Mapping

The simplest form of mapping uses a string to specify the exact output path:

export const MAP = [
    {
        source: "zombie.behavior.json",
        target: "BP/entities/zombie.behavior.json"
    },
    {
        source: "zombie.entity.png",
        target: "RP/textures/entity/zombie.png"
    }
];

This approach gives you complete control over where each file is placed in the output.

Auto-Mapping

Auto-mapping automatically determines the target path based on the file’s extension and a predefined mapping configuration. This saves time and ensures consistent file organization.

:auto Keyword

The :auto keyword uses the file’s extension to determine the appropriate output directory, preserving any subdirectory structure from the source path.

export const MAP = [
    // Source in root of module
    {
        source: "zombie.behavior.json",
        target: ":auto"  // → BP/entities/zombie.behavior.json
    },
    // Source in a subfolder
    {
        source: "hostile/zombie.entity.png",
        target: ":auto"  // → RP/textures/entity/hostile/zombie.png
    }
];

Notice how the hostile/ subfolder from the source is preserved in the output path.

It’s also important to note that the zombie.entity.png file becomes zombie.png in the output. The .entity part of the extension is used by the auto-mapping system to route the file to the correct directory (RP/textures/entity/) and is then removed from the final filename. This powerful pattern allows you to organize files by their type and purpose within your modules. For more details on how to configure this behavior, see Auto-Mapping Configuration.

:autoFlat Keyword

The :autoFlat keyword works like :auto but ignores the directory structure of the source file, placing the file directly in the auto-mapped root folder.

This is useful when your source files are organized into subdirectories, but you want a flat structure in the final output.

export const MAP = [
    {
        source: "entities/hostile/zombie.behavior.json",
        target: ":autoFlat"  // → BP/entities/zombie.behavior.json
    },
    {
        source: "models/zombie.geo.json",
        target: ":autoFlat"  // → RP/models/entity/zombie.geo.json
    }
];

Here, the entities/hostile/ and models/ paths are discarded, and the files are placed directly in the directories determined by their extensions.

Auto-Mapping Extensions

The behavior of auto-mapping is controlled by a set of rules in the auto-map.ts file. To learn how to view and customize these rules, see the Auto-Mapping Configuration documentation.

Glob Patterns

The source property supports glob patterns to match multiple files at once. This is useful in combination with the :auto keyword to map multiple files at once without collisions.

export const MAP = [
    {
        source: "entities/*.behavior.json",
        target: ":auto"
    }
];

This will match all files in the entities/ directory that end with .behavior.json and map them automatically based on their names.

Directory Mapping

When you specify a target path that ends with /, ModularMC will move the source file to that directory while preserving the original filename.

export const MAP = [
    {
        source: "zombie.behavior.json",
        target: "BP/entities/"  // → BP/entities/zombie.behavior.json
    },
    {
        source: "textures/zombie.png",
        target: "RP/textures/entity/"  // → RP/textures/entity/zombie.png
    },
    {
        source: "models/*.geo.json",
        target: "RP/models/"  // → Export all geo.json files to RP/models/
    }
];

This is particularly useful when you want to organize files into specific directories without having to specify the full filename in the target path.

Warning

Paths without extensions are treated as filenames, not directories. You must explicitly end the path with / to indicate a directory target.

Target Objects

For advanced scenarios, you can use target objects to have fine-grained control over the output path.

{
    source: "entities/zombie_boss.behavior.json",
    target: {
        path: ":autoFlat",
        subpath: "bosses",
        name: "zombie_emperor.behavior.json"
    }
    // Results in: BP/entities/bosses/zombie_emperor.behavior.json
}

path: string

The base directory for the output. It can be one of three value types:

A string path (e.g., "BP/entities"): Sets the exact base directory.
":auto": Uses the auto-mapping directory but preserves the source’s subdirectory structure.
":autoFlat": Uses the auto-mapping directory but discards the source’s subdirectory structure.

subpath: string (optional)

An optional string that defines an additional directory structure to be inserted between the path and the name.

name: string

The output filename. It can be one of two value types:

A string name (e.g., "custom_zombie.behavior.json"): Sets the exact output filename.
":auto": Uses the source filename and applies any extension transformations defined in your auto-map.ts configuration (e.g., .entity.png becomes .png). :autoFlat is not valid here.