This is an official reference page. If you encounter inaccuracies or would like to expand the page, please message the developers in the #phantom-modding channel on BYG Discord.
¶ Links
- Functions: Combat
- Functions: Combat Action
- Functions: Combat Targeted
- Functions: Overworld
- Functions: Overworld Action
- Functions: Overworld Event
- Functions: Subsystem Events
- Functions: Other
¶ Overview
Functions are classes implementing one of the function interfaces that exist in the game. All function interfaces require a class to include a Run method with various context specific signatures. Overall, the purpose of a function class is to implement an arbitrary effect on game state that can run on demand. A function class can declare any number of different fields depending on what information is required to execute its effect.
What's powerful about function classes is that they are typically used in interface typed lists in different databases. Normally, a class schema is rigidly defined: if you want ability to change unit health, you need to set up a field for doing that, lock in an HP float field describing how much health is changed, etc. With functions, databases do not have to lock in unused fields or unused data blocks. An overworld event that does nothing yields a short YAML file, while an event that spawns an action, modifies a pilot and creates an overworld entity gets context specific fields on function objects.
Here's an example of how serialized function list looks like in YAML. Notice how every entry has a different type specified with a !Type prefix. It's important to know the function name to use it in YAML, as that lets the game know what type to attempt loading for a given entry:
Here is how a function is declared in the codebase. Simply inherit from one of the function interfaces, implement the required Run method and that's it, it can be used in any config with an interface field of that type.
Each function can inherit from more than one function interface. For example, modifying the mobile base memory is a broadly useful function in many different contexts. Why redundantly implement it in 3 different places? Here's an example of how this can be implemented:
¶ Modding
Code mods can introduce new functions and enable use of new functions in YAML configs. Simply declare a class inheriting from one of the function interfaces and it will be discovered by the game. If this doesn't occur (in some special cases, the class might not be discovered), try decorating it with a [TypeHinted] attribute to ensure it's automatically registered to YAML tag mappings.
When creating a new function class, make sure the name of your class is globally unique rather than just unique to your mod's assembly: a tag mapping will not be created if a given alias is already registered to another class.
If you're looking for a sample code mod implementing a new function, check out the WaitOnUse by EchKode: it's an awesome, exceptionally well documented example.