Modding:Lua Modding

Modding Getting Started

Agent Component Overview

Editing existing files

Adding new assets

Writing new code

Lua Modding

Lua is a scripting language. It's interpreted at runtime, and is used by a wide range of programs (World of Warcraft add-ons are written in Lua, for example)

Getting Started

If you aren't familiar with Lua, there are countless tutorials.

You can edit the Lua with anything you want (Notepad++, etc).

If you aren't familiar with the agent system, you can read about it here. You'll also need to be familiar with the XML system.

The Basics

The basics are straightforward:

1.Create a .lua file and add it to data/Mods (in the Starmancer installation directory). Give it a unique name 2.Add the Engine.Mods.Lua.LuaModComponent component, setting the luaFileName to whatever you named your .lua file (don't include the extension)

That's it

Events

Everything in Starmancer is driven by events. Your lua script will need to subscribe to events if you want it to do something useful.

There are 3 types of events:

• Event - Local to agent, like OnDied
• GlobalEvent - Invoked Globally, not associated with any specific agent, like OnTick.
• Query - Used to retrieve information from components (technically these are no different from Events)

You can view all current events if you click the provided links.

Internally, events are strings, so you can create your own. You'll have to use AgentEventParameter.GetBase to do this

Subscribing

Subscribe to events by using either allEvents (also includes queries) or allGlobalEvents.

The element type is LuaEvent.

You must provide:

string eventName	The Starmancer event, like OnDamaged or OnTick
int priority	Priority to subscribe with (optional). Default is 0.
string luaMethod	The name of the method in your lua file to invoke when the event is received.

Parameters

In order to use a C# parameter you need to explicitly specify it with allParameterTypes. You don't not need to include the namespace.

By convention, all events have a matching parameter, like

OnPlaced	OnPlacedParameter
OnRepositioned	OnRepositionedParameter
OnQueryPosition	OnQueryPositionParameter

If you're unsure of the name, you can search in the docs. Occasionally, parameters will have different names.

To create parameters, use the provided Get method, like:

OnDamagedParameter.Get("God", 2);

caller.CallEvent 

Many query parameters also have static methods that you can invoke to get whatever data you're interested in.

Storing Data

To store data, use:

caller.StoreData(string key, DynValue value)

All primitive values are accepted. Passed values will be saved.

To get the data back, use:

caller.GetData(string key)

Initialization

Any code that you write before the first function will be executed when your component is created. Use this if you have some data that you want to initialize.

Example

Here's an example that ties it all together.

The lua is calling some random events in the initialization.

It subscribes to OnClicked, and damages all active colonists (doing 2 damage).

It also subscribes to OnClicked, with 2 sets of priorities. Also storing and retrieving data.

It subscribes to the GlobalEvent, OnTick (invoked once per second)

caller.CallEvent("OnHealed", OnHealedParameter.Get(5));

position = OnQueryPositionParameter.Query_position(caller.GetAgent());
print(position[1]);

function OnClicked(parameter)
    print("OnClicked");
 
    allActiveColonists = OnQueryActiveSleeveParameter.Query_allActiveColonists()

    for _, colonist in ipairs(allActiveColonists) do
        print(colonist);
        parameter = OnDamagedParameter.Get("God", 2);
        colonist.CallEvent_FromLua("OnDamaged", parameter);         
    end
end


function OnPreEventInvoked(parameter)
    print("pre"); 
    parameter.amountOfHealthToStore = 999;
    caller.StoreData("myKey", 5); 
    print(caller.GetData("myKey"));
end


function OnPostEventInvoked(parameter)
    print("post");   
end
 

function OnTick(parameter)
    print("OnTick");
end

Here's the XML: It adds a lua mod to the agent Toolbar Objects Button. Note that I didn't need to include the OnClickedParameter, because I'm not using it.

<xml>
    name:agents
    <Toolbar-ObjectsButton>
        <componentLookup>
            <Component>
                type:Engine.Mods.Lua.LuaModComponent                
                luaFileName:myLua

                <allEvents>
                    eventName:OnClicked
                    priority:0
                    luaMethod:OnClicked
                </allEvents>

                <allEvents>
                    eventName:OnHealed
                    priority:10
                    luaMethod:OnPreEventInvoked
                </allEvents>

                <allEvents>
                    eventName:OnHealed
                    priority:-1
                    luaMethod:OnPostEventInvoked
                </allEvents>

                <allGlobalEvents>
                    eventName:OnTick
                    priority:0
                    luaMethod:OnTick
                </allGlobalEvents>

                allParameterTypes:AgentEventParameter
                allParameterTypes:OnQueryActiveSleeveParameter
                allParameterTypes:OnDamagedParameter
                allParameterTypes:OnHealed
            </Component>           
        </componentLookup>
    </Toolbar-ObjectsButton>
</xml>

That's It

Modding is an incredibly complex topic. There's no way to quickly understand it. You'll have to get a good grasp for the internal mechanics of Starmancer if you want to create an meaningful mods. Becoming familiar with the events is the best way to try to understand the basic agent-event flow.