Aeternitas 18+ Edition - Complete Modding Guide

Learn how to create and modify content for Aeternitas 18+ Edition

Introduction

Aeternitas 18+ Edition features a powerful modding system that allows you to extend and modify the game in almost any way imaginable. Mods are JavaScript files that run in a sandboxed environment with full access to the game's modding API.

What Can Mods Do?

• Add new items, rooms, NPCs, and crafting recipes
• Modify existing game content
• Create custom commands
• Override base game commands
• Hook into game events (turns, room entry, item taking, commands)
• Change the starting room
• Override character creation
• Create full conversion mods
• Register custom grammar templates
• Access parser information (command slots, tense)

Mod Safety

Mods run in an isolated execution context using new Function(), providing a level of sandboxing. However, mods have full access to the game state through the modAPI object. Always load mods from trusted sources.

---

Getting Started

Loading a Mod

1. In-Game Method:
   • Type loadmod in the game
   • Select a .js file from your computer
   • The mod will load automatically
2. Mod Menu:
   • Type mods or mod to open the mod menu
   • View loaded mods and their status

Basic Mod Structure

A mod is a JavaScript file that receives a modAPI object:

modAPI.displayOutput({
    success: true,
    message: "Hello from my mod!"
});

Modded Saves

When mods are loaded, the game enters "MODDED MODE":

• Use save modded to save your modded game state
• Use load modded to load a modded save
• Warning: Modded saves require the same mods to be loaded to work properly

---

Modding API Reference

Core Objects

modAPI.game

Direct reference to the game instance. Use with caution - prefer API methods when available.

---

Content Creation

Items

modAPI.addItem(itemId, itemData)

Adds a new item to the game.

Parameters:

• itemId (string): Unique identifier for the item
• itemData (object): Item properties

Item Properties:

{
    name: "Item Name",              
    description: "Item description", 
    takeable: true,                 
    consumable: false,              
    heals: 0,                      
    encumbrance: 1,                
    value: 10,                     
    weapon: false,                 
    damage: 0,                     
    armor: false,                  
    defense: 0,                    
    magical: false,                
    lightSource: false,            
    readable: {                    
        lore: "Text content"
    },
    openable: false,               
    container: false,              
    fragile: false,                
    hidden: false                  
}

Example:

modAPI.addItem("magic_sword", {
    name: "Magic Sword",
    description: "A glowing blade that pulses with energy.",
    takeable: true,
    weapon: true,
    damage: 15,
    encumbrance: 3,
    magical: true,
    value: 100
});

modAPI.modifyItem(itemId, itemData)

Modifies an existing item. Properties are merged with existing data.

Example:

modAPI.modifyItem("mailbox", {
    description: "A mailbox. [MODIFIED BY MY MOD]"
});

modAPI.removeItem(itemId)

Removes an item from the game.

Rooms

modAPI.addRoom(roomId, roomData)

Adds a new room to the game world.

Room Properties:

{
    name: "Room Name",              
    description: "Room description", 
    exits: {                        
        north: "room_id",
        south: "another_room",
        east: "yet_another_room"
    },
    items: ["item1", "item2"],     
    hiddenItems: ["secret_item"],   
    entity: "npc_id",               
    visited: false,                 
    locked: false,                  
    dark: false,                    
    gatheringResources: {           
        harvest: {
            materials: ["herb", "wood"],
            maxUses: 5,
            uses: 5,
            exhausted: false
        }
    }
}

Example:

modAPI.addRoom("my_custom_room", {
    name: "Custom Room",
    description: "A room created by my mod!",
    exits: {
        north: "west_of_house"
    },
    items: ["magic_sword"],
    visited: false,
    locked: false,
    dark: false
});

modAPI.modifyRoom(roomId, roomData)

Modifies an existing room.

modAPI.removeRoom(roomId)

Removes a room from the game.

NPCs/Entities

modAPI.addEntity(entityId, entityData)

Adds a new NPC/entity to the game.

Entity Properties:

{
    name: "Entity Name",            
    description: "Entity description",
    gender: "male",                 
    peaceful: true,                 
    health: 50,                     
    maxHealth: 50,                  
    damage: 5,                      
    defense: 2,                     
    drops: ["item1", "item2"],      
    fleeChance: 0.3,                
    tamable: false,                 
    merchant: false,                
    inventory: ["item1"],           
    prices: {                       
        "item1": 10
    },
    relationship: 0,                
    friendshipLevel: 0,            
    romanceLevel: 0,                
    relationshipStage: "stranger",  
    currentLocation: "room_id",     
    favoriteGifts: ["item1"],       
    dialogue: {                     
        greeting: "Hello!",
        topics: {
            "topic": "Response text"
        }
    },
    aiRoutine: {                    
        schedule: [
            {time: 6, location: "room_id", behaviors: ["behavior1"]}
        ]
    }
}

Example:

modAPI.addEntity("my_npc", {
    name: "Mod NPC",
    description: "A friendly NPC created by my mod.",
    peaceful: true,
    health: 50,
    maxHealth: 50,
    currentLocation: "my_custom_room",
    relationship: 0,
    relationshipStage: "stranger",
    dialogue: {
        greeting: "Hello! I'm from a mod!",
        topics: {
            "mod": "This mod adds cool features!",
            "help": "I can help you with modding!"
        }
    }
});

modAPI.modifyEntity(entityId, entityData)

Modifies an existing entity.

modAPI.removeEntity(entityId)

Removes an entity from the game.

Crafting Recipes

modAPI.addRecipe(recipeId, recipeData)

Adds a new crafting recipe.

Recipe Properties:

{
    name: "Recipe Name",            
    description: "Recipe description",
    materials: ["item1", "item2"],  
    result: "result_item",          
    skill: "alchemy",               
    skillLevel: 5,                  
    discovered: false               
}

Example:

modAPI.addRecipe("magic_potion", {
    name: "Magic Potion",
    description: "A potion that restores health.",
    materials: ["herb", "water"],
    result: "healing_potion",
    skill: "alchemy",
    skillLevel: 3
});

---

Crafting System

Crafting Specialization

modAPI.getCraftingSpecialization()

Gets the player's current crafting specialization.

Returns:

{
    specialization: "weapons" | "armor" | "tools" | "consumables" | "materials" | null,
    level: 0-20
}

Example:

const spec = modAPI.getCraftingSpecialization();
if (spec.specialization === "weapons") {
    modAPI.displayOutput({
        success: true,
        message: `You're specialized in weapons crafting at level ${spec.level}!`
    });
}

modAPI.setCraftingSpecialization(specialization, level)

Sets the player's crafting specialization.

Parameters:

• specialization (string) - One of: "weapons", "armor", "tools", "consumables", "materials"
• level (number, optional) - Specialization level (0-20)

Example:

modAPI.setCraftingSpecialization("weapons", 5);
modAPI.displayOutput({
    success: true,
    message: "You've been granted weapons crafting specialization at level 5!"
});

Crafting Orders

modAPI.getCraftingOrders()

Gets all active crafting orders.

Returns: Object mapping order IDs to order data.

modAPI.createCraftingOrder(orderId, orderData)

Creates a new crafting order for the player.

Parameters:

{
    orderId: "unique_order_id",
    orderData: {
        giver: "entity_id",           // NPC giving the order
        giverName: "NPC Name",         // Optional, defaults to entity name
        recipeId: "recipe_id",        // Recipe to craft
        recipeName: "Recipe Name",     // Optional, defaults to recipe name
        quantity: 1,                   // How many to craft
        reward: 50,                     // Gold reward
        deadline: 100                   // Turns until deadline (optional)
    }
}

Example:

modAPI.createCraftingOrder("special_order_1", {
    giver: "blacksmith",
    giverName: "Riven",
    recipeId: "iron_sword",
    quantity: 2,
    reward: 150,
    deadline: 50
});
modAPI.displayOutput({
    success: true,
    message: "A new crafting order has been created!"
});

modAPI.completeCraftingOrder(orderId)

Marks a crafting order as completed and gives the reward.

Returns: true if successful, false if order not found.

Example:

if (modAPI.completeCraftingOrder("special_order_1")) {
    modAPI.displayOutput({
        success: true,
        message: "Order completed! You received your reward."
    });
}

Crafting Contests

modAPI.getCraftingContests()

Gets all active crafting contests.

Returns: Object mapping contest IDs to contest data.

modAPI.createCraftingContest(contestId, contestData)

Creates a new crafting contest.

Parameters:

{
    contestId: "unique_contest_id",
    contestData: {
        opponent: "entity_id",         // NPC to compete against
        opponentName: "NPC Name",      // Optional
        recipeId: "recipe_id",        // Recipe to craft
        recipeName: "Recipe Name",     // Optional
        quantity: 1,                   // How many to craft
        opponentSkill: 60,             // Opponent's crafting skill
        deadline: 50                   // Turns until deadline (optional)
    }
}

Example:

modAPI.createCraftingContest("championship_1", {
    opponent: "blacksmith",
    opponentName: "Riven",
    recipeId: "masterwork_sword",
    quantity: 1,
    opponentSkill: 90,
    deadline: 30
});
modAPI.displayOutput({
    success: true,
    message: "A crafting championship has begun!"
});

modAPI.submitContestEntry(contestId, itemId)

Submits an item for a crafting contest.

Returns:

{
    quality: "masterwork" | "fine" | "normal" | "poor",
    qualityScore: 0-5
} | null

Example:

const result = modAPI.submitContestEntry("championship_1", "masterwork_sword_fine");
if (result) {
    modAPI.displayOutput({
        success: true,
        message: `You submitted a ${result.quality} quality item (score: ${result.qualityScore})!`
    });
}

Relationship System API

The relationship system allows mods to manage polyamory, jealousy, conflicts, group activities, milestones, and NPC-to-NPC relationships.

Polyamory

modAPI.getPolyamoryEnabled()

Checks if polyamory is enabled.

Returns: true or false

modAPI.setPolyamoryEnabled(enabled)

Enables or disables polyamory mode.

modAPI.getPlayerRomanticRelationships()

Gets all NPC IDs the player is in a romantic relationship with.

Returns: Array of NPC IDs

modAPI.addRomanticRelationship(npcId)

Adds an NPC to the player's romantic relationships.

modAPI.removeRomanticRelationship(npcId)

Removes an NPC from the player's romantic relationships.

Jealousy System

modAPI.getNPCJealousy(npcId)

Gets an NPC's jealousy level (0-100).

modAPI.setNPCJealousy(npcId, level)

Sets an NPC's jealousy level (0-100).

Relationship Conflicts

modAPI.getNPCConflict(npcId1, npcId2)

Gets conflict data between two NPCs, or null if no conflict exists.

modAPI.createNPCConflict(npcId1, npcId2, reason, intensity)

Creates a conflict between two NPCs.

Parameters:

• npcId1 (string) - First NPC ID
• npcId2 (string) - Second NPC ID
• reason (string) - Reason for the conflict
• intensity (number, optional) - Conflict intensity (1-10, default: 5)

modAPI.resolveNPCConflict(npcId1, npcId2)

Removes a conflict between two NPCs.

Group Activities

modAPI.getGroupActivityParticipants()

Gets the list of NPC IDs currently participating in a group activity.

modAPI.startGroupActivity(npcIds)

Starts a group activity with the specified NPCs.

Parameters: Array of NPC IDs or single NPC ID

modAPI.endGroupActivity()

Ends the current group activity.

Relationship Milestones

modAPI.getRelationshipMilestones(npcId)

Gets all relationship milestones for an NPC.

Returns: Array of milestone objects

modAPI.addRelationshipMilestone(npcId, milestoneType, data)

Adds a relationship milestone for an NPC.

Parameters:

• npcId (string) - NPC ID
• milestoneType (string) - Type of milestone (e.g., "first_kiss", "first_date", "moving_in")
• data (object, optional) - Additional milestone data

NPC-to-NPC Relationships

modAPI.getNPCToNPCRelationship(npcId1, npcId2)

Gets relationship data between two NPCs, or null if no relationship exists.

modAPI.setNPCToNPCRelationship(npcId1, npcId2, friendship, relationshipStage)

Sets the relationship between two NPCs.

Parameters:

• npcId1 (string) - First NPC ID
• npcId2 (string) - Second NPC ID
• friendship (number) - Friendship level
• relationshipStage (string, optional) - Relationship stage (default: "stranger")

Example:

// Enable polyamory
modAPI.setPolyamoryEnabled(true);

// Add romantic relationship
modAPI.addRomanticRelationship("miller");

// Create conflict between NPCs
modAPI.createNPCConflict("miller", "blacksmith", "Business rivalry", 7);

// Start group activity
modAPI.startGroupActivity(["miller", "blacksmith"]);

// Add milestone
modAPI.addRelationshipMilestone("miller", "first_kiss", {location: "mill"});

NPC Dynamic Features API

These APIs allow mods to customize NPC behavior, conversations, reactions, preferences, and schedules.

Dynamic Conversation

modAPI.setNPCApproachMessages(npcId, messages)

Sets messages that an NPC will say when the player approaches them.

Parameters: Array of message strings or single message string

modAPI.setNPCTriggerPhrases(npcId, phrases)

Sets trigger phrases that will cause the NPC to respond in specific ways.

Parameters: Object mapping phrases to responses

Example:

modAPI.setNPCTriggerPhrases("miller", {
    "hello": "Greetings! Welcome to my mill.",
    "weather": "It's a fine day for milling grain.",
    "help": "I can help you with grain and flour!"
});

modAPI.setNPCConversationTopics(npcId, topics)

Sets conversation topics the NPC can discuss.

Parameters: Array of topic strings

World Reactions

modAPI.setNPCWorldReactions(npcId, reactions)

Sets how an NPC reacts to weather, time of day, seasons, and world events.

Parameters: Object with reaction handlers

Example:

modAPI.setNPCWorldReactions("miller", {
    weather: {
        rain: "The rain makes the mill wheel turn faster!",
        snow: "It's too cold to work outside today."
    },
    timeOfDay: {
        night: "I'm usually asleep at this hour, but I'll help you.",
        morning: "Good morning! Ready for a day of milling?"
    },
    season: {
        spring: "Spring is the best time for fresh grain!",
        winter: "Winter is slow, but I keep the mill running."
    }
});

Preferences

modAPI.setNPCPreferences(npcId, preferences)

Sets an NPC's likes and dislikes for gifts, activities, and conversation topics.

Example:

modAPI.setNPCPreferences("miller", {
    favoriteGifts: ["grain", "flour"],
    dislikedGifts: ["rotten_food"],
    favoriteTopics: ["milling", "grain", "farming"],
    dislikedTopics: ["war", "violence"]
});

Personality

modAPI.setNPCPersonality(npcId, personality)

Sets an NPC's personality traits, quirks, and speech patterns.

Example:

modAPI.setNPCPersonality("miller", {
    traits: ["hardworking", "friendly", "optimistic"],
    quirks: ["talks about grain a lot"],
    speechPattern: "rural",
    emotionalRange: "stable"
});

Schedule/Routine

modAPI.setNPCRoutine(npcId, routine)

Sets an NPC's daily routine/schedule.

Parameters: Array of routine entries

Example:

modAPI.setNPCRoutine("miller", [
    {time: "morning", location: "mill", action: "milling"},
    {time: "afternoon", location: "village_square", action: "selling"},
    {time: "evening", location: "mill", action: "resting"}
]);

Region API

The region system allows mods to organize rooms by geographical areas.

modAPI.setRoomRegion(roomId, region)

Sets the region for a room.

Returns: true if successful, false if room not found

modAPI.getRoomRegion(roomId)

Gets the region for a room.

Returns: Region string or null

modAPI.getRoomsByRegion(region)

Gets all room IDs in a specific region.

Returns: Array of room IDs

Example:

// Set region for a new room
modAPI.setRoomRegion("my_mod_room", "Hollow Ridge");

// Get all rooms in a region
const hollowRidgeRooms = modAPI.getRoomsByRegion("Hollow Ridge");
modAPI.displayOutput({
    success: true,
    message: `Found ${hollowRidgeRooms.length} rooms in Hollow Ridge.`
});
}

---

Command System

Custom Commands

modAPI.addCommand(commandName, handler)

Adds a new custom command.

Handler Function:

function handler(target) {

    return {
        success: true,              
        message: "Command output"   
    };
}

Example:

modAPI.addCommand("hello", (target) => {
    return {
        success: true,
        message: "Hello from my mod!"
    };
});

Command Overrides

modAPI.overrideCommand(commandName, handler)

Overrides a base game command. Return null to use default behavior.

Example:

modAPI.overrideCommand("look", (target) => {
    const game = modAPI.game;
    if (game.currentRoom === "my_custom_room") {
        return {
            success: true,
            message: "You see a custom room with special mod content!"
        };
    }

    return null;
});

---

Event Hooks

Command Hooks

modAPI.onCommand(callback)

Hooks into all commands before they execute.

Callback Function:

function callback(command) {

    return null;
}

Example:

modAPI.onCommand((command) => {
    if (command.toLowerCase().includes("test")) {
        return {
            handled: true,
            message: "Command intercepted by mod!"
        };
    }
    return null;
});

Turn Hooks

modAPI.onTurn(callback)

Called every turn.

Callback Function:

function callback(turn, game) {

}

Example:

let turnCount = 0;
modAPI.onTurn((turn, game) => {
    turnCount++;
    if (turnCount % 10 === 0) {
        modAPI.displayOutput({
            success: true,
            message: `You've taken ${turnCount} turns!`
        });
    }
});

Room Entry Hooks

modAPI.onRoomEnter(callback)

Called when entering a room.

Callback Function:

function callback(roomId, game) {

}

Example:

modAPI.onRoomEnter((roomId, game) => {
    if (roomId === "my_custom_room") {
        modAPI.displayOutput({
            success: true,
            message: "You enter a special mod room!"
        });
    }
});

Item Take Hooks

modAPI.onItemTake(callback)

Called when an item is taken.

Callback Function:

function callback(itemId, game) {

}

Example:

modAPI.onItemTake((itemId, game) => {
    if (itemId === "magic_sword") {
        modAPI.displayOutput({
            success: true,
            message: "The sword pulses with energy!"
        });
        game.score += 10;
    }
});

---

Advanced Features

Starting Room Override

modAPI.setStartingRoom(roomId)

Changes the starting room for new games.

Example:

modAPI.setStartingRoom("my_custom_room");

Character Creation Override

modAPI.overrideCharacterCreation(handler)

Overrides the character creation process.

Handler Function:

function handler(game) {

    game.playerName = "Mod Character";

    return true;
}

Full Conversion Mods

modAPI.setFullConversion(enabled)

Marks the mod as a full conversion mod.

Example:

modAPI.setFullConversion(true);

Save/Load Overrides

modAPI.overrideSave(handler)

Overrides the save system.

Handler Function:

function handler(game) {

    return {
        customData: "value"
    };
}

modAPI.overrideLoad(handler)

Overrides the load system.

Handler Function:

function handler(saveData, game) {

}

Grammar Templates

modAPI.registerGrammar(grammarName, grammarRules)

Registers a custom grammar template for the parser.

Example:

modAPI.registerGrammar("pirate", {
    greetings: ["ahoy", "arr", "yo ho"],
    affirmations: ["aye", "arr", "aye aye"]
});

modAPI.getGrammar(grammarName)

Retrieves a registered grammar template.

Parser Information

modAPI.getCommandSlots()

Returns the extracted command slots including manner, tone, purpose, condition, and deep semantic intent (Schank's Theory).

Returns:

{
    manner: "gently" | null,        
    tone: "lovingly" | null,         
    purpose: "to comfort her" | null, 
    condition: "if she agrees" | null, 

    closeness: "intimate" | "friendly" | "neutral" | "hostile" | "distant",
    mood: "happy" | "sad" | "angry" | "playful" | "serious" | "romantic" | "fearful" | "calm" | "excited" | "bored" | "confident" | "shy" | "grateful" | "jealous" | "guilty" | "proud" | "neutral",
    roleIntention: "protector" | "attacker" | "helper" | "companion" | "healer" | "teacher" | "romantic" | "provider" | "leader" | "follower" | "negotiator" | "explorer" | null,
    targetIntimacy: "intimate" | "personal" | "social" | "public" | null,
    socialRuleViolation: "none" | "minor" | "major"
}

Example:

const slots = modAPI.getCommandSlots();

            
modAPI.getChainOfIntent()
            
Returns the chain-of-intent analysis for complex commands with multiple purposes.
            
Returns:
            
{
    primaryIntent: {
        type: "primary",
        action: "CONTACT",  
        original: "grab"
    } | null,
    secondaryIntents: [
        {
            type: "secondary",
            intent: "PROTECTIVE",
            description: "pull her away from danger",
            strength: "high"
        }
    ],
    combinedIntent: "CONTACT_PROTECTIVE" | null,
    intentChain: ["CONTACT", "PROTECTIVE"],
    emotionalContext: "concerned" | "caring" | "protective" | "romantic" | "friendly" | "hostile" | null,
    socialContext: "public" | "private" | "group" | "one-on-one"
}
            
Example:
            

const chain = modAPI.getChainOfIntent();

            
modAPI.normalizeActionToPrimitive(action)
            
Maps action synonyms to universal primitives (ATTACK, CONTACT, AFFECTION, MOVEMENT, EXAMINE, TAKE, GIVE, COMMUNICATE, USE, CRAFT, DROP, OPEN, CLOSE, EAT, READ, WEAR, REMOVE).
            
Parameters:
            

                
action (string) - The action word to normalize
            
            
Returns: The normalized primitive (e.g., "ATTACK", "CONTACT") or the original action if no match is found.
            
Example:
            
modAPI.normalizeActionToPrimitive("smack");  
modAPI.normalizeActionToPrimitive("pat");   
modAPI.normalizeActionToPrimitive("peck");  
modAPI.normalizeActionToPrimitive("unknown"); 
            
modAPI.getCommandTense()
            
Returns the detected command tense ("past", "present", "future", "ongoing").
            
Using Semantic Intent in Commands
            
You can use semantic intent analysis to create more nuanced command responses based on the player's emotional state, relationship level, and intent.
            
Example:
            
modAPI.addCommand("comfort", (target) => {
    const slots = modAPI.getCommandSlots();
    const chain = modAPI.getChainOfIntent();
    const player = modAPI.getPlayer();

    if (chain.secondaryIntents.some(i => i.intent === "COMFORTING")) {

        if (slots.closeness === "intimate") {
            return {
                success: true,
                message: "You hold them close, offering warmth and reassurance."
            };
        } else if (slots.closeness === "friendly") {
            return {
                success: true,
                message: "You offer a friendly pat on the shoulder and words of encouragement."
            };
        }
    }

    if (slots.mood === "caring") {
        return {
            success: true,
            message: "You express genuine concern and care."
        };
    }
    return {
        success: true,
        message: "You try to comfort them."
    };
});

modAPI.onCommand((command, target) => {
    const normalized = modAPI.normalizeActionToPrimitive(command.split(" ")[0]);
    if (normalized === "ATTACK") {
        const slots = modAPI.getCommandSlots();

        if (slots.mood === "playful") {
            modAPI.displayOutput({
                success: true,
                message: "You playfully strike at them!"
            });
        } else if (slots.socialRuleViolation === "major") {
            modAPI.displayOutput({
                success: false,
                message: "That would be a serious violation of social norms!"
            });
        }
    }
});
            

            
Utility Functions
            
Display Output
            
modAPI.displayOutput(message)
            
Displays a message to the player.
            
Example:
            
modAPI.displayOutput({
    success: true,
    message: "Hello from mod!"
});
            
Execute Command
            
modAPI.executeCommand(command)
            
Executes a game command programmatically.
            
Example:
            
modAPI.executeCommand("go north");
            
Random Number
            
modAPI.getRandom(min, max)
            
Returns a random integer between min and max (inclusive).
            
Example:
            
const roll = modAPI.getRandom(1, 20);
            
Player Data
            
modAPI.getPlayer()
            
Returns player data object.
            
Returns:
            
{
    name: "Player Name",
    inventory: ["item1", "item2"],
    equipment: {weapon: "sword", armor: "leather"},
    stats: {str: 10, int: 8, ...},
    skills: {alchemy: 5, ...},
    currentRoom: "room_id",
    money: 100,
    health: 50,
    mana: 30
}
            
modAPI.setPlayer(playerData)
            
Sets player data. Only provided properties are updated.
            
Example:
            
modAPI.setPlayer({
    money: 1000,
    health: 100
});
            
Game State Access
            
modAPI.getItems()
            
Returns all items object.
            
modAPI.getWorld()
            
Returns all rooms object.
            
modAPI.getEntities()
            
Returns all entities object.
            
modAPI.getRecipes()
            
Returns all crafting recipes object.
            

            
Best Practices
            
1. Unique Identifiers
            
Always use unique, descriptive IDs for your content:
            

modAPI.addItem("my_mod_sword_v2", {...});

modAPI.addItem("sword", {...}); 
            
2. Error Handling
            
Check if content exists before modifying:
            
if (modAPI.getItems()["mailbox"]) {
    modAPI.modifyItem("mailbox", {...});
}
            
3. Mod Compatibility
            
Prefix your mod's content with a unique identifier:
            
const MOD_PREFIX = "my_mod_";
modAPI.addItem(MOD_PREFIX + "sword", {...});
modAPI.addRoom(MOD_PREFIX + "room", {...});
            
4. Clean Up
            
Provide unload functionality if needed:
            

const addedItems = ["my_mod_sword", "my_mod_potion"];

            
5. Documentation
            
Document your mod's features and requirements:
            
modAPI.displayOutput({
    success: true,
    message: `
=== My Mod v1.0 ===
Features:
- New items: Magic Sword, Health Potion
- New room: Custom Chamber
- New command: 'mymod'
- Requires: No dependencies
    `
});
            
6. Testing
            
Test your mod thoroughly:
            

                
Test with and without other mods
                
Test save/load functionality
                
Test command conflicts
                
Test edge cases
            
            

            
Examples
            
Example 1: Simple Item Mod
            

modAPI.addItem("modded_apple", {
    name: "Modded Apple",
    description: "A shiny red apple created by a mod.",
    takeable: true,
    consumable: true,
    heals: 20,
    encumbrance: 1
});
modAPI.displayOutput({
    success: true,
    message: "Modded Apple mod loaded!"
});
            
Example 2: Custom Room and NPC
            

modAPI.addRoom("mod_tavern", {
    name: "Mod Tavern",
    description: "A cozy tavern added by a mod.",
    exits: {
        north: "west_of_house"
    },
    items: ["modded_apple"],
    entity: "mod_bartender",
    visited: false
});

modAPI.addEntity("mod_bartender", {
    name: "Mod Bartender",
    description: "A friendly bartender from a mod.",
    peaceful: true,
    currentLocation: "mod_tavern",
    relationship: 0,
    dialogue: {
        greeting: "Welcome to the mod tavern!",
        topics: {
            "drink": "I serve the finest modded beverages!",
            "mod": "This tavern was created by a mod!"
        }
    }
});
modAPI.displayOutput({
    success: true,
    message: "Mod Tavern mod loaded! Type 'go mod tavern' to visit!"
});
            
Example 3: Custom Command with Hook
            

modAPI.addCommand("modtest", (target) => {
    return {
        success: true,
        message: "Mod test command works! Target: " + (target || "none")
    };
});

modAPI.onCommand((command) => {
    if (command.toLowerCase().startsWith("modtest")) {
        modAPI.displayOutput({
            success: true,
            message: "[HOOK] Command intercepted!"
        });
    }
    return null; 
});
modAPI.displayOutput({
    success: true,
    message: "Command mod loaded! Try 'modtest'!"
});
            
Example 4: Turn-Based Event
            
let modTurnCount = 0;
modAPI.onTurn((turn, game) => {
    modTurnCount++;

    if (modTurnCount % 5 === 0 && game.health < game.maxHealth) {
        game.health = Math.min(game.maxHealth, game.health + 1);
        modAPI.displayOutput({
            success: true,
            message: "[MOD] You feel slightly refreshed! (+1 HP)"
        });
    }
});
modAPI.displayOutput({
    success: true,
    message: "Regeneration mod loaded! You'll heal 1 HP every 5 turns."
});
            
Example 5: Full Conversion Mod
            

modAPI.setFullConversion(true);

modAPI.setStartingRoom("mod_start_room");

modAPI.addRoom("mod_start_room", {
    name: "Modded Starting Area",
    description: "You begin your adventure in a modded world!",
    exits: {
        east: "mod_town"
    },
    items: ["mod_starter_sword"],
    visited: false
});

modAPI.overrideCharacterCreation((game) => {
    game.playerName = "Mod Character";

    return true; 
});
modAPI.displayOutput({
    success: true,
    message: "Full conversion mod loaded! Starting in modded world..."
});
            

            
Troubleshooting
            
Mod Won't Load
            
Problem: Mod file doesn't load or shows error.
            
Solutions:
            

                
Check JavaScript syntax errors
                
Ensure file is .js format
                
Check browser console for errors
                
Verify modAPI is used correctly
            
            
Mod Conflicts
            
Problem: Mod conflicts with base game or other mods.
            
Solutions:
            

                
Use unique IDs with prefixes
                
Check for ID conflicts before adding content
                
Test mod compatibility
                
Load mods in different orders
            
            
Save/Load Issues
            
Problem: Modded saves don't work.
            
Solutions:
            

                
Ensure same mods are loaded when loading save
                
Check if mod uses save/load overrides
                
Verify mod state is saved correctly
                
Use save modded and load modded commands
            
            
Commands Not Working
            
Problem: Custom commands don't execute.
            
Solutions:
            

                
Check command name conflicts
                
Verify handler returns correct format
                
Check if command is overridden
                
Test command hook interception
            
            
Content Not Appearing
            
Problem: Added items/rooms/NPCs don't appear.
            
Solutions:
            

                
Verify IDs are correct
                
Check if content is added to correct locations
                
Ensure rooms have proper exits
                
Verify entities have currentLocation set
            
            

            
API Quick Reference
            
Content Management
            

                
addItem(itemId, itemData) - Add item
                
modifyItem(itemId, itemData) - Modify item
                
removeItem(itemId) - Remove item
                
addRoom(roomId, roomData) - Add room
                
modifyRoom(roomId, roomData) - Modify room
                
removeRoom(roomId) - Remove room
                
addEntity(entityId, entityData) - Add entity
                
modifyEntity(entityId, entityData) - Modify entity
                
removeEntity(entityId) - Remove entity
                
addRecipe(recipeId, recipeData) - Add recipe
            
            
Crafting
            

                
getCraftingSpecialization() - Get specialization
                
setCraftingSpecialization(specialization, level) - Set specialization
                
getCraftingOrders() - Get all orders
                
createCraftingOrder(orderId, orderData) - Create order
                
completeCraftingOrder(orderId) - Complete order
                
getCraftingContests() - Get all contests
                
createCraftingContest(contestId, contestData) - Create contest
                
submitContestEntry(contestId, itemId) - Submit contest entry
            
            
Commands
            

                
addCommand(commandName, handler) - Add command
                
overrideCommand(commandName, handler) - Override command
            
            
Hooks
            

                
onCommand(callback) - Command hook
                
onTurn(callback) - Turn hook
                
onRoomEnter(callback) - Room entry hook
                
onItemTake(callback) - Item take hook
            
            
Advanced
            

                
setStartingRoom(roomId) - Set starting room
                
setCurrentRoom(roomId) - Teleport player
                
overrideCharacterCreation(handler) - Override character creation
                
setFullConversion(enabled) - Mark as full conversion
                
overrideSave(handler) - Override save
                
overrideLoad(handler) - Override load
                
registerGrammar(grammarName, grammarRules) - Register grammar
                
getGrammar(grammarName) - Get grammar
                
getCommandSlots() - Get command slots (including semantic intent)
                
getChainOfIntent() - Get chain-of-intent analysis
                
normalizeActionToPrimitive(action) - Normalize action to primitive
                
getCommandTense() - Get command tense
            
            
Utilities
            

                
displayOutput(message) - Display message
                
executeCommand(command) - Execute command
                
getRandom(min, max) - Random number
                
getPlayer() - Get player data
                
setPlayer(playerData) - Set player data
                
getItems() - Get all items
                
getWorld() - Get all rooms
                
getEntities() - Get all entities
                
getRecipes() - Get all recipes
            
            

            
Support
            
For modding support:
            

                
Check the test mod (test_mod.js) for examples
                
Review the game's source code for implementation details
                
Test your mods in a safe environment before sharing
            
            

            
Happy Modding!