Modding:Lua Modding
Modding Getting Started |
Agent Component Overview |
Editing existing files |
Adding new assets |
Writing new code |
Contents
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.