MOD Creation Tutorial & Lua API

1. Quick Start

1.1 What is a MOD?

A MOD is a player-made content pack that modifies creature stats, skills, skins, and hitbox properties. The game ships with two example MODs — DemoCharacterMod and DemoSkinsMod — located in the game’s MOD directory (see path above). Copy and modify them to get started quickly.

1.2 MOD Directory Location

1.3 MOD Directory Structure

Mods/
├── DemoCharacterMod/           ← Full example (stats+skills+hitbox+skin)
│   ├── mod.json                ← MOD manifest
│   ├── preview.jpg             ← Preview image
│   ├── CharacterAsset/
│   │   └── allo.txt            ← Allosaurus config (all 4 types)
│   └── SkinsAsset/
│       └── Crooked mouth.png   ← Skin texture
│
├── DemoSkinsMod/               ← Skin-only MOD example
│   ├── mod.json
│   ├── preview.jpg
│   └── SkinsAsset/
│       ├── allo_deser_allo.txt ← Skin script
│       └── deser_allo.png      ← Skin texture
│
└── MyFirstMod/                 ← Your MOD root directory
    ├── mod.json
    └── CharacterAsset/
        └── allo.txt

1.4 Create mod.json

{
  "Name": "MyFirstMod",
  "Author": "Your Name",
  "Version": "1.0",
  "SupportedVersion": "0.6.*",
  "Priority": 0,
  "Description": "My first MOD",
  "PreviewImagePath": "preview.jpg",
  "Tags": "Character"
}

1.5 The In-Game MOD Interface at a Glance

On the login screen click MOD Management to open the MOD interface. It has three tabs — Local MODs, Workshop, Manage MODs — plus the Create MOD and Set Directory buttons, covering a MOD author's whole journey from creation to testing.

1.6 Create Your MOD (Recommended for Beginners)

The game has a built-in MOD creation tool — no need to make folders by hand:
① Log in (creating a MOD requires login; the MOD is bound to your account).
② MOD Management → click Create MOD.
③ Fill in the name (letters/digits/underscore/hyphen only, 1–64 chars), author, version, supported version, description, tags, and pick a template.
④ Click Create — the system generates the directory skeleton (mod.json plus the template's example script folder).
⑤ The MOD then appears on the Manage MODs tab as a draft, not yet on the local load list.

1.7 Edit and Preview

① Find your MOD on Manage MODs. If you have "Set Directory," the MOD is synced to that external folder and you can open it directly in a text editor; otherwise edit the Lua scripts (CharacterAsset/*.txt, etc.), skin PNGs, and preview.jpg inside its folder in the game MOD directory.
② Use the inline Edit button to change version, supported version, description, and tags (the name is locked).
③ When done, click Preview to push the draft into the Local MODs load list.

1.8 Test in Game (Author Dev-Test Loop)

1. Create: MOD Management → Create MOD → pick a template → Create (generates a draft; see 1.6).
2. Edit: edit the scripts and metadata on Manage MODs (see 1.7).
3. Preview: click Preview to move the draft into the Local MODs load list.
4. Enable: switch to Local MODs, confirm the MOD status is "Enabled" (green) and "Supported Version" is green (red means it is incompatible with the current game version — fix SupportedVersion).
5. Test: enter single-player or create a room — the modified stats/skills/skins take effect immediately.
6. Iterate: go back to Manage MODs and edit the scripts → create a local Host room so the preview snapshot refreshes from the latest draft → re-enter the match to verify. After Sync Preview is enabled once, neither a game restart nor another Sync Preview click is needed.
7. Distribute: when satisfied, use Export to produce a .mod file to share; on Steam you can also Upload to Workshop to publish publicly.

1.9 Sync Preview Mode (Development Testing)

Sync Preview in Manage MODs creates a separate runtime snapshot of your draft and registers it in the local load list. The authoring source stays in the Manage MODs directory; Sync Preview is not publishing and does not upload the MOD to the Workshop.

1.10 Export .mod (Sharing and Installation)

Export packages the current working copy from Manage MODs into a compressed .mod file and opens the system save-location picker. The package is rooted at the directory containing mod.json and includes scripts, images, and other MOD files. Export does not enable preview, alter your draft, make the MOD public, or upload it to the Workshop.

1. Author: in Manage MODs, click Export, save the .mod through the system file picker, then send that file to testers or players.
2. Recipient: on the Local MODs tab, click Import MOD, select the received .mod (or a supported .zip), then confirm it appears in the local load list and is enabled.
3. Multiplayer: before joining or creating a MOD-enabled room, every participant should use the same MOD content, version, and enabled state. An exported package is not a substitute for publishing to the Workshop.

2. Character Stat MOD

Create a .txt file in the CharacterAsset/ directory and define a CharacterAsset table to modify creature attributes. Omitted fields keep original values. Below is the complete allo.txt from the bundled DemoCharacterMod, showing every available field.

2.1 Full Example (allo.txt from DemoCharacterMod)

-- Complete Allosaurus stat configuration (*do not delete below)
CharacterAsset = {
    name    = "Allosaurus",     -- Display name
    enable  = true,            -- Enable creature
    jump    = false,           -- Allow jumping (needs matching animation)
    race    = "allo",          -- Race tag (*required, unique match key)
    ropoda  = 0,               -- Nest type (-1=none, 0=theropod, 1=sauropod, 2=ornithischian)
    ropode  = 0,               -- Egg type (-1=none, 0=theropod, 1=sauropod, 2=ornithischian)
    volume  = 2,               -- Size class 0~5 (light→super)
    rank    = 7,               -- Star rating 0~12 (S1~SS tier)
    branch  = 3,               -- Family classification 0~25
    habit   = 0,               -- Habit (0=land, 1=hydrophilic, 2=marine reptile, 3=aquatic, 4=amphibian, 5=flying)
    type    = 0,               -- Category (0=carnivore, 1=herbivore, 2=aquatic, 3=arthropod, 4=mammal, 5=flying)
    taste   = 0,               -- Diet (0=carnivore, 1=flowers, 2=leaves, 3=omnivore)
    spawn   = 0,               -- Reproduction (0=oviparous, 1=viviparous)
    health  = 26503.0,         -- Max health
    hunger  = 12227.0,         -- Max hunger
    water   = 3128.0,          -- Max water
    oxygen  = 474.0,           -- Max oxygen
    stamina = 100.0,           -- Max stamina
    attack  = 2802.0,          -- Base attack damage
    defend  = 779.0,           -- Base defense
    pen     = 5,               -- Penetration level 0~10
    ten     = 3,               -- Tenacity level 0~10
    restore = 266.0,           -- Natural recovery rate
    consume = 100.0,           -- Cruise consumption
    weight  = 3600.0,          -- Body weight (kg)
    speed   = 27.01,           -- Walk speed (km/h)
    swim    = 13.5,            -- Swim speed (km/h)
    flying  = 0.0,             -- Flight speed (km/h)
    runSpeed    = 54.01,       -- Sprint speed (km/h)
    turnSpeed   = 0.61,        -- Turn rate (degrees/sec)
    growtime    = 1560.0,      -- Time to reach adult (seconds)
    ovumtime    = 1080.0,      -- Egg generation interval (seconds)
    hatching    = 2210.0,      -- Incubation time (seconds)
    safe        = 1800.0,      -- Juvenile protection period (seconds)
    skill   = "LifeDrain,3;",  -- Innate EX skill
    gene    = "",              -- Innate gene
}

2.2 Classification & Identity

2.3 Survival & Combat

2.4 Movement Speed (km/h)

2.5 Time Parameters

2.6 Organ Efficiency (0.0 ~ 1.0)

2.7 Body Dimensions & Innate Traits

3. Skill MOD

Use the CharacterSkill table to modify creature attack skills. Each skill is a key-value pair (keys can be named freely). Can be combined with CharacterAsset in the same .txt file.

3.1 Full Example (from DemoCharacterMod)

CharacterSkill = {
    attack1 = {
        Race         = "allo",      -- *Required* race tag
        AttackOrder  = 1,           -- Attack slot index (1=mouth1, 2=mouth2...)
        AttackType   = 0,           -- Attack type 0~7 (see enum below)
        DamageMode   = 0,           -- Damage mode 0~2 (see enum below)
        Area         = nil,         -- Allowed areas: nil=any, {0,1}=land+shallow only
        AttackRange  = 1.0,         -- Collision radius (meters)
        Modify       = 2.0,         -- Damage multiplier (1=no change)
        UseStamina   = 0.01,        -- Stamina cost percentage (0=default)
        TriggerSkill = "Scars,2;",  -- Skill triggered on hit (format: "Name,Level;")
    },
    attack2 = {
        Race         = "allo",
        AttackOrder  = 2,
        AttackType   = 1,           -- Tail
        DamageMode   = 1,           -- AOE
        AttackRange  = 3.0,
        Modify       = 0.8,
        UseStamina   = 0.03,
        TriggerSkill = "Blood,2;",
    },
}

3.2 AttackType Enum

3.3 DamageMode Enum

3.4 Area Enum

4. Hitbox MOD

Use the CharacterHitGroup table to modify armor penetration rate and damage multiplier for each body part — create weak spots or reinforced armor.

4.1 Body Part Constants

4.2 Example (from DemoCharacterMod)

CharacterHitGroup = {
    head = {
        Race              = "allo",
        PartType          = BODY_HEAD,
        PenetrationRate   = 0.6,    -- 0~1 (higher = easier to penetrate)
        DamageMultiplier  = 1.5,    -- 0.5~2 (>1 = more damage taken)
    },
    body = {
        Race              = "allo",
        PartType          = BODY_BODY,
        PenetrationRate   = 0.05,   -- Almost impenetrable
        DamageMultiplier  = 0.8,    -- 20% damage reduction
    },
    belly = {
        Race              = "allo",
        PartType          = BODY_BELLY,   -- Belly (value=7)
        PenetrationRate   = 0.9,    -- Very high penetration
        DamageMultiplier  = 1.8,    -- Heavy bonus damage
    },
}

5. Gene BUFF MOD

The Gene BUFF MOD overrides the values and config of existing genes/skills/BUFFs via the global table CharacterGeneBuff. Like CharacterAsset, the script is XLua (.txt) and can live in the same file or a dedicated GeneBuff/ subfolder.

5.1 Config Structure (CharacterGeneBuff)

CharacterGeneBuff = {
    -- Key = the existing gene tag to override (get TAGs from the Skills & Genes list page)
    Bleed = {
        Repeat  = "COVER",   -- Optional: overwrite rule
        Upgrade = "EXP",     -- Optional: upgrade mode
        With    = "",        -- Optional: attached effect DSL, format tag,level;
        Copes   = "",        -- Optional: counter target tag
        Effects = {          -- *Required* per-level table (replaces the original per-level values)
            { Level = 1, Probability = 0.55, Effect = 0.03, Duration = 5 },
            { Level = 2, Probability = 0.65, Effect = 0.05, Duration = 7 },
        }
    }
}

5.2 Modifiable Top-Level Fields

5.3 Effects Per-Level Fields

5.4 Available Enums

5.5 Full Example (bundled DemoCharacterMod/GeneBuff/gene_buff.txt)

CharacterGeneBuff = {
    -- ① Override the per-level values of the existing gene Metabolism
    Metabolism = {
        Effects = {
            { Level = 1, Effect = 0.12, Skillful = 0   },
            { Level = 2, Effect = 0.18, Skillful = 100 },
        }
    },
    -- ② Override the trigger probability, values and duration of the existing skill gene Bleed
    Bleed = {
        Effects = {
            { Level = 1, Probability = 0.55, Effect = 0.03, Duration = 5 },
            { Level = 2, Probability = 0.65, Effect = 0.05, Duration = 7 },
        }
    }
}

5.6 Grant Innate Genes to a Creature

-- In the creature's CharacterAsset script, use the gene field to grant innate genes. Format: GeneName,Level;
CharacterAsset = {
    race = "allo",
    gene = "Metabolism,2;",
}

5.7 Loading & Constraints

• Applies immediately: once the override succeeds, birth / trigger / execution all read the overridden values.
• Strict reference validation: With must be tag,level, no self-reference, the referenced tag must exist, and the level must be in range; Copes must exist and not self-reference. Any failure rejects the override (never fails silently).
• No valid Effects → that override fails.
• Session-level restore: leaving / disabling / resetting the MOD automatically restores the overridden genes, preventing cross-match residue.
• Dual-side parity: the server must load the same MOD via GAME_MODS; hashes must match to join; /modReload hot-reloads gene values.

6. Skin MOD

Use the CharacterSkin table to add custom skins. Each .txt file defines one skin. Texture files go in a SkinsAsset/ folder within your MOD directory. See the bundled DemoSkinsMod for a complete example.

6.1 Skin Script

CharacterSkin = {
    Race = "allo",                              -- *Required* race tag
    Name = "Crooked mouth",                      -- *Required* unique skin name
    Path = "SkinsAsset/Crooked mouth.png",       -- *Required* texture path (relative to MOD root)
}

6.2 Texture Requirements

• Format: PNG or JPG.
• Resolution: match the original texture (typically 2048×2048 or 4096×4096).
• Path must be relative to MOD root — no absolute paths.

6.3 Multi-Skin Directory Example

MySkinMod/
├── mod.json
├── preview.jpg
└── SkinsAsset/
    ├── allo_crooked.txt   ← CharacterSkin { Race="allo", Name="Crooked mouth", ... }
    ├── crooked_allo.png   ← Texture file
    ├── rex_volcano.txt    ← Multiple races in one MOD is fine
    └── volcano_rex.png

7. Advanced: Management & Distribution

7.1 Priority System

When multiple MODs modify the same field of the same race, the larger Priority value runs later and wins. Default is 0. Same-priority MODs run in alphabetical order.

7.2 Lua Sandbox Security

• os, io: system commands and file I/O are blocked.
• dofile, loadfile, package: arbitrary file execution and dynamic library loading are blocked.

7.3 Packaging as .mod File

Compress all files in your MOD folder as ZIP, then rename to .mod. Ensure mod.json is at the archive root. Both .mod and .zip are recognized.

7.4 Server MODs

Servers specify MODs via the GAME_MODS environment variable (comma-separated):
GAME_MODS=DemoCharacterMod,MySkinMod
All server-required MODs must be installed and enabled on clients to join. Extra client-only MODs will not apply on that server. Admins can use /modReload to hot-reload MOD config.