Modding:XML Editing

From Starmancer Wiki
Jump to: navigation, search
Modding
Getting Started 		Agent
Component Overview 		Editing
existing files 		Adding
new assets 		Writing
new code

XML Editing

All Agents in the game are loaded and created when the game first starts, using data provided in data/agents.xml.

Everything is composed of Records and Entries. Records can contain nested records.

The syntax is fairly straight-forward: 

<Record>
    entry:value
    entry:value
    <Subrecord>
        entry:value
    </Subrecord>
</Record>

If the same entry or subrecord name is used multiple times, it will automatically be stored as an array.

Why Bother?

Literally everything in the game is loaded from xml files. If you make any mod, there's almost a 90% chance that you'll have to edit some xml somewhere

  • Adjusting how quickly colonists get hungry
  • Adding new sprites
  • Adding brand new components (via LUA or DLL mod)

Example

Here's a snippet from the large shelf: 

<ShelfStandardBigEntity>
    Name:Shelf Standard Big Entity
    <allKeys>
        recordID:Object
        value:Object
    </allKeys>
    <allKeys>
        recordID:TradeableContainer
        value:TradeableContainer
    </allKeys>
    <componentLookup>
        <Component>
            type:World.Item.ItemContainerComponent
            recordID:58920cfe-6385-4259-8d31-a1e5104cb120
            maximumCapacity:8
        </Component>  
            type:World.Colonist.Health.HitPointComponent
            recordID:56b4d8f0-2f01-4cab-84e8-f51ae9d96f54
            maxHealth:8
        </Component>
    </componentLookup>
    guid_:3d8b34da-4062-49a3-b5b7-44d4934d7c78
</ShelfStandardBigEntity>

Broken Down

This sets the name of the agent (used as a unique identifier if other components want to reference this agent) to "Shelf Standard Big Entity". 

Name:Shelf Standard Big Entity

Some keys are added: Object and TradeableContainer.

*recordId is used to uniquely identify an element in a list, allowing you to edit a specific element. In this case, it's a bit unnecessary, but it's automatically generated for all list elements. RecordID's are guids. Use any guid that you want. The odds of 2 objects ever having the same guid is almost 0. Just Google "guid generator" to create guids. RecordID's are optional 

<allKeys>
    recordID:Object
    value:Object
</allKeys>
<allKeys>
    recordID:TradeableContainer
    value:TradeableContainer
</allKeys>

Two components are added:

  • ItemContainerComponent - With capacity for 8 items
  • HitPointComponent - Stores the shelf's health
 <componentLookup>
    <Component>
            type:World.Item.ItemContainerComponent
            recordID:58920cfe-6385-4259-8d31-a1e5104cb120
            maximumCapacity:8
        </Component>  
            type:World.Colonist.Health.HitPointComponent
            recordID:56b4d8f0-2f01-4cab-84e8-f51ae9d96f54
            maxHealth:8
        </Component>
</componentLookup>

Making Changes

You could directly edit agents.xml, but what would happen if both you and another modder made changes to the same file? There would definitely be some sort of conflict. Ideally the mods are somehow "drag and drop", where every modder can change only the parts that they're interested in.

XML Name

Every XML file has a unique name. In the case of agents.xml, that unique name is "agents". This name is set at the very top of the xml file, and looks like: 

name:agents

When creating your own xml modifications, you only need to provide that unique name. (also at the top). Your xml file will automatically be merged with the existing xml file (when the game is launched).

Commands

Command Description
name The name of the xml file that you want to modify.

You can only modify 1 xml file per file. So create a new xml file if you want to modify another file. (required)

priority Use this to set the priority of when your xml file should be loaded.

Higher priorities are loaded LATER. Use this to overwrite another modder's xml file. (optional)

shouldAppend If true, elements in a list will be appended to the existing list. Otherwise, the elements will be replaced.

By default, subrecords are automatically appended, but entries are not.

deleteRecord If true, the subrecord containing this record will be deleted. Used to remove components, among other things
recordID Uniquely identifies a subrecord in a list. It's a GUID. This is actually optional.

You only need this if you want to let another modder easily edit your file

Real Example

Here's an example file that modifies "Toolbar-ObjectsButton". These files would be placed under data/Mods.

The specific component is LuaModComponent

(You can't put comments in the real xml files, but I added them for explanation) 

<xml>
    name:agents // Identifies the original xml file to modify    
    priority:9001 // Priority is high, so this file will overwrite any other changes (if there's a conflict)
    <Toolbar-ObjectsButton> // Make changes to Toolbar-ObjectsButton
        <componentLookup>
            <Component> // Add a new component, of type LuaModComponent
                type:Engine.Mods.Lua.LuaModComponent
                recordID:d8452789-4bd1-46c8-ac6c-10e15f5a9f95 // uniquely identifies this component
                                                              // (we manually created this. It's optional)
                luaFileName:myLua
                shouldPassCaller:True
                <allEvents>
                    recordID:OnClicked
                    eventName:OnClicked
                    priority:0
                    luaMethod:OnClicked
                </allEvents>
                allParameterTypes:OnClickedParameter
            </Component>
            <Component>
                recordID:ba8b6bcb-3df1-47f2-b4e6-7d67640351d5 // (this identifies the specific component that we're modifying from the original agents.xml. We found this by looking in agents.xml)
               
                <objectToPlace>
                    gameObjectReference:212 // override the gameobject to be 212.
                </objectToPlace>
            </Component>
           <Component>
                recordID:56b4d8f0-2f01-4cab-84e8-f51ae9d96f54 // (again, we found this by searching in agents.xml)
                deleteRecord:true // this component will be deleted
            </Component>
        </componentLookup>
    </Toolbar-ObjectsButton>
</xml>

Here's another example that adds names to the colonist name pool. 

<xml>
    name:nameLookup
    <MaleNames>
        shouldAppend:true // if shouldAppend:true was not included, it would have overridden the first 5 names. This can sometimes be what you wanted, and it's why all list subrecord element have a unique recordID
        
        allFirstNames:Aaron
        allFirstNames:Adam
        allFirstNames:Adrian
        allFirstNames:Aiden
        allFirstNames:Alexander
    </MaleNames>
</xml>

Naming Conventions

For consistency, we (the Starmancer devs) use a set of terms to describe most agents in the game. It's useful to know these so that you can better find the correct agent in the xml files

Menu Entry The agent that exists in the menu, like a button.

Example: Oven Menu Entry

Blueprint The agent that the user sees when they attempt to build an object.

Example: Oven Blueprint

Entity The agent that actually exists in the "real" (game) world.

This is the agent that you typically want to edit. Example: Oven Entity

If you add a brand new object to the game, you'll almost always have to create a Menu Entry, Blueprint, and Entity

That's It

Add your xml files to data/Mods/. You can create your own subfolders to group your files however you want (as long as it's all under data/Mods/

XML file editing isn't super complicated. It helps if you look at real examples, like agents.xml. Play around with it, try to break things.

Retrieved from "https://starmancerwiki.com/mediawiki/index.php?title=Modding:XML_Editing&oldid=808"