Custom Hooks and Triggers

From Star Ruler 2 Wiki
Jump to: navigation, search

What are they

The game defines certain object classes to provide functionality that is implemented via Scripts.

They are either called Hooks or Triggers but are, for the most part, very similar.

How does it work

The game overs predefined classes which you can inherit from in order to add new Hooks.

Then put your code under scripts\definitions\fileName.as and you will be able to use your created Hook in the mod editor!

Then you only need to overwrite the inherited methods you want to use and you are good to go.

The full list of inherited functions can be found in generic_hooks.as and examples are in the

  • _effects.as files. (eg: generic_effects.as)

All default hooks you can apply in the mod editor can be found in the _effect.as files.

A (not so) simple example

Lets jump straight into Code.

import buildings;
from buildings import IBuildingHook;
import resources;
import util.formatting;
import systems;
import saving;
import influence;
from influence import InfluenceStore;
from statuses import IStatusHook, Status, StatusInstance;
from resources import integerSum, decimalSum;
import orbitals;
from orbitals import IOrbitalEffect;
import attributes;
import hook_globals;
import research;
import empire_effects;
import repeat_hooks;
import planet_types;
#section server
import object_creation;
from components.ObjectManager import getDefenseDesign;
#section all


class IsFriendlyGate : GenericEffect {
	Document doc("This object behaves as if it is a gate that connects to the TEAMS gate network.");
#section server
	void enable(Object& obj, any@ data) const override {
		if(obj.owner !is null && obj.owner.valid) {
			if(obj.owner.team != -1)
				registerTeam(obj.owner.team, obj);
			else
				obj.owner.registerStargate(obj);
		}
	}

	void ownerChange(Object& obj, any@ data, Empire@ prevOwner, Empire@ newOwner) const override {
		print("Change");
		if(prevOwner !is null && prevOwner.valid) {
			if(prevOwner.team != -1)
				unregisterTeam(prevOwner.team, obj);
			else
				prevOwner.unregisterStargate(obj);
		}
		if(newOwner !is null && newOwner.valid)
		{
			if(newOwner.team != -1)
				registerTeam(newOwner.team, obj);
			else
				newOwner.registerStargate(obj);
		}
	}

	void disable(Object& obj, any@ data) const override {
	print("kill");
		if(obj.owner !is null && obj.owner.valid)
			if(obj.owner.team != -1)
				unregisterTeam(obj.owner.team, obj);
			else
				obj.owner.unregisterStargate(obj);
	}
	
	void registerTeam(int team, Object& obj) const
	{
		for(uint empireIdx = 0; empireIdx < getEmpireCount(); empireIdx++)
		{
			auto@ empire = getEmpire(empireIdx);
			if(empire.team != team)
				continue;
			empire.registerStargate(obj);
		}
	}
	
	void unregisterTeam(int team, Object& obj) const
	{
		for(uint empireIdx = 0; empireIdx < getEmpireCount(); empireIdx++)
		{
			auto@ empire = getEmpire(empireIdx);
			if(empire.team != team)
				continue;
			empire.unregisterStargate(obj);
		}
	}
	
#section all
};

This code adds a new Effect which, when applied to a Gate, makes it usable by all players in a Team.

Imports allow us to use classes and functions provided in other files. The best way to find out what you need to import is to look at the default scripts.

the #section lines define if code gets compiled on the server or the client. The default methods do nothing so are fine for the client. On the server we want to override the default functions to add our functionality so we define them in #section server.

class IsFriendlyGate : GenericEffect {

we define the name of our Hook (IsFriendlyGate) and inherit from the GenericEffect Class, this class can be used to provide effects for arbitrary Objects.

Document doc("This object behaves as if it is a gate that connects to the TEAMS gate network.");

Defines the description that will show up in the mod editor. Argument works similar and allows you to set options in the Editor.

void enable(Object& obj, any@ data) const override
void ownerChange(Object& obj, any@ data, Empire@ prevOwner, Empire@ newOwner) const override
void disable(Object& obj, any@ data) const override

are default Functions provided by Generic Effect, they get called when the Effect is applied(enable) removed(disable) or the object changes owner.

There are other functions that can be overridden for the full list check generic_hooks.as. Eg you can have a function that is called each tick for as long as the effect is active.

register/unregisterTeam are helper functions which do the actual work of marking the gate as usable for a whole team.

In order for the game to load the file you need to create the Path scripts\definitions in your mod directory and place it as .as file. (eg: gateHooks.as).

If there are any script errors the game will show the compile error in the console. If it doesn't show any errors you should be able to add the Effect as a Hook for Gates.

Look for GateUnpacked in the Status list and replace the IsGate Hook with IsFriendlyGate and it should work!

If your still confused try the IRC Channel or poke the existing script files. Happy Modding!