Services - Revision history

Imbion at 15:45, 16 October 2025

2025-10-16T15:45:54Z

MistressNebula: Fixes + doc reference

2025-03-13T15:52:04Z

Fixes + doc reference

← Older revision		Revision as of 15:52, 13 March 2025
Line 1:		Line 1:
	Services are special files whose purpose is to listen to specific actions the game can perform and then run some code whenever they occur.<br>		Services are special files whose purpose is to listen to specific actions the game can perform and then run some code whenever they occur.<br>
	The base game already has a few built-in services that can be used for reference, but this page will go over how to make a new service from scratch and how to register new callbacks.		The base game already has a few built-in services that can be used for reference, but this page will go over how to make a new service from scratch and how to register new callbacks.

			If you're looking for the complete list of events you can hook your code up to, you can find it [[Service Events\|here]].

	=== How to make a service ===		=== How to make a service ===
	First, navigate to your mod's <code>Data>Script>[namespace]</code> folder. Once there, add a <code>services</code> folder if there isn't one already and, inside of it, create yet another folder. This final folder can have any name you want as long as it has no special characters in it, but it's best to stick to something that is as close as possible to the name you want to give to your service. For ~~Example~~, the base game's DebugTools service is inside the debug_tools folder.		First, navigate to your mod's <code>Data>Script>[namespace]</code> folder. Once there, add a <code>services</code> folder if there isn't one already and, inside of it, create yet another folder. This final folder can have any name you want as long as it has no special characters in it, but it's best to stick to something that is as close as possible to the name you want to give to your service. For example, the base game's DebugTools service is inside the debug_tools folder.
	Finally, create a text file inside of this folder and call it init.lua. Make sure that .lua is part of the file's extension and not still a portion of its name.		Finally, create a text file inside of this folder and call it init.lua. Make sure that .lua is part of the file's extension and not still a portion of its name.

Line 32:		Line 34:
	<pre>		<pre>
	function MyService:OnInit()		function MyService:OnInit()
	assert(self, 'MyService:OnInit() : self is null!')		assert(self, 'MyService:OnInit() : self is null!')
	PrintInfo("\n<!> MyService: Init..")		PrintInfo("\n<!> MyService: Init..")
	end		end
	</pre>		</pre>
	All this function does is print whether or not our service has been registered correctly when the service engine is loaded. To make it run, all we need to do is to add this line inside the service's Subscribe function:		All this function does is print whether or not our service has been registered correctly when the service engine is loaded. To make it run, all we need to do is to add this line inside the service's Subscribe function:
	<pre>		<pre>
	med:Subscribe("MyService", EngineServiceEvents.Init, function() self:OnInit() end)		med:Subscribe("MyService", EngineServiceEvents.Init, function() self:OnInit() end)
	</pre>		</pre>

Line 45:		Line 47:
	==== Callbacks with parameters ====		==== Callbacks with parameters ====
	Many events contain parameters that get sent alongside their service messages so that services can reference and interact with them. These parameters are packaged into an argument array with starting index 0. An example of this is LossPenalty, whose argument 0 is the current GameProgress instance, which is to say, the save data itself. We need to pass this parameter along if we want to make use of it.<br>		Many events contain parameters that get sent alongside their service messages so that services can reference and interact with them. These parameters are packaged into an argument array with starting index 0. An example of this is LossPenalty, whose argument 0 is the current GameProgress instance, which is to say, the save data itself. We need to pass this parameter along if we want to make use of it.<br>
	If you're wondering what that discaded parameter is, it's your service's class. At no point you'll ever need this, since you're already working with it anyway.		If you're wondering what that first, discaded parameter is, it's your service's class. At no point you'll ever need this, since you're already working with it anyway.
	<pre>		<pre>
	function MyService:OnLossPenalty(save)		function MyService:OnLossPenalty(save)
	[...]		[...]
	end		end

IDK: add category tags

2025-01-22T01:49:46Z

add category tags

← Older revision		Revision as of 01:49, 22 January 2025
Line 56:		Line 56:
	</pre>		</pre>
	And that's all there is to it! Every service callback can be reduced to these simple steps!		And that's all there is to it! Every service callback can be reduced to these simple steps!

			[[Category:Scripting]]
			[[Category:Quick Reference]]

MistressNebula: Fix discarded parameter description

2025-01-21T13:10:53Z

Fix discarded parameter description

← Older revision		Revision as of 13:10, 21 January 2025
Line 3:		Line 3:

	=== How to make a service ===		=== How to make a service ===
	~~The first thing you want to do is to~~ navigate to your mod's <code>Data>Script>[namespace]</code> folder. ~~Then, if not present~~, add a <code>services</code> folder and, inside of it, yet another folder. This final folder can have any name you want as long as it has no special characters in it, but it's best to stick to something that is as close as possible to the name you want to give to your service. For Example, the base game's DebugTools service is inside the debug_tools folder.		First, navigate to your mod's <code>Data>Script>[namespace]</code> folder. Once there, add a <code>services</code> folder if there isn't one already and, inside of it, create yet another folder. This final folder can have any name you want as long as it has no special characters in it, but it's best to stick to something that is as close as possible to the name you want to give to your service. For Example, the base game's DebugTools service is inside the debug_tools folder.
	Finally, create a text file inside of this folder and call it init.lua. Make sure that .lua is part of the file's extension and not still a portion of its name.		Finally, create a text file inside of this folder and call it init.lua. Make sure that .lua is part of the file's extension and not still a portion of its name.

Line 45:		Line 45:
	==== Callbacks with parameters ====		==== Callbacks with parameters ====
	Many events contain parameters that get sent alongside their service messages so that services can reference and interact with them. These parameters are packaged into an argument array with starting index 0. An example of this is LossPenalty, whose argument 0 is the current GameProgress instance, which is to say, the save data itself. We need to pass this parameter along if we want to make use of it.<br>		Many events contain parameters that get sent alongside their service messages so that services can reference and interact with them. These parameters are packaged into an argument array with starting index 0. An example of this is LossPenalty, whose argument 0 is the current GameProgress instance, which is to say, the save data itself. We need to pass this parameter along if we want to make use of it.<br>
	If you're wondering what that discaded parameter is, it's ~~just the name of the event that triggered the callback~~. In this ~~case~~, ~~<code>"LossPenalty"</code>~~.		If you're wondering what that discaded parameter is, it's your service's class. At no point you'll ever need this, since you're already working with it anyway.
	<pre>		<pre>
	function MyService:OnLossPenalty(save)		function MyService:OnLossPenalty(save)

MistressNebula: First creation

2025-01-17T18:16:52Z

First creation

New page

Services are special files whose purpose is to listen to specific actions the game can perform and then run some code whenever they occur. 
The base game already has a few built-in services that can be used for reference, but this page will go over how to make a new service from scratch and how to register new callbacks.

=== How to make a service ===
The first thing you want to do is to navigate to your mod's <code>Data>Script>[namespace]</code> folder. Then, if not present, add a <code>services</code> folder and, inside of it, yet another folder. This final folder can have any name you want as long as it has no special characters in it, but it's best to stick to something that is as close as possible to the name you want to give to your service. For Example, the base game's DebugTools service is inside the debug_tools folder.
Finally, create a text file inside of this folder and call it init.lua. Make sure that .lua is part of the file's extension and not still a portion of its name.

Once you're done, open this file with your text editor of choice. You will want to copy and paste this whole block inside of it:
<pre>
require 'origin.services.baseservice'

local MyService = Class('MyService', BaseService)

function MyService:initialize()
end

function BaseService:Subscribe(med)
end

SCRIPT:AddService("MyService", MyService:new())
return MyService
</pre>

This is the smallest possible service you can make. It simply creates the class, registers it, and then returns it. You can change "MyService" into whatever name you want, of course. 
Right now, though, this service of ours literally does nothing. Let's change that. 
You can use the initialize function to define starting parameters or other global data related to your service. Keep in mind, however, that these values are not kept in between game sessions. Always remember to store your save data inside your SV structure if you want to be able to retrieve it after closing the game. 
What we need to use to make a service work, however, is the Subscribe function. This is the function responsible for registering callbacks so that the game knows to call them whenever a specific event takes place. You can find a list of all Engine Events present in the game and their parameters [[Service Events|here]].

==== Creating a Callback ====
The first thing we need is the function we want to call. This can have any name you like, but it's best if its name references the event it is subscribed to in some way. 
We will use this simple print function as an example. Make sure to put it below your service's declaration but before its Subscribe function:
<pre>
function MyService:OnInit()
assert(self, 'MyService:OnInit() : self is null!')
PrintInfo("\n<!> MyService: Init..")
end
</pre>
All this function does is print whether or not our service has been registered correctly when the service engine is loaded. To make it run, all we need to do is to add this line inside the service's Subscribe function:
<pre>
med:Subscribe("MyService", EngineServiceEvents.Init, function() self:OnInit() end)
</pre>

If you run the game now, you will notice that nothing happens still. This is because this file has never been loaded by the game. To make it load, create a <code>main.lua</code> file in your mod's <code>Data>Script>[namespace]</code> folder and write <code>require "[namespace].services.[service_folder]"</code> in it. Now the game will know it needs to load your service and you will see its OnInit function being called as expected.

==== Callbacks with parameters ====
Many events contain parameters that get sent alongside their service messages so that services can reference and interact with them. These parameters are packaged into an argument array with starting index 0. An example of this is LossPenalty, whose argument 0 is the current GameProgress instance, which is to say, the save data itself. We need to pass this parameter along if we want to make use of it. 
If you're wondering what that discaded parameter is, it's just the name of the event that triggered the callback. In this case, <code>"LossPenalty"</code>.
<pre>
function MyService:OnLossPenalty(save)
[...]
end

function MyService:Subscribe(med)
med:Subscribe("MyService", EngineServiceEvents.LossPenalty, function(_, args) self:OnLossPenalty(args[0]) end )
end
</pre>
And that's all there is to it! Every service callback can be reduced to these simple steps!

← Older revision		Revision as of 15:45, 16 October 2025
Line 4:		Line 4:
	If you're looking for the complete list of events you can hook your code up to, you can find it [[Service Events\|here]].		If you're looking for the complete list of events you can hook your code up to, you can find it [[Service Events\|here]].

	=== How to make a service ===		== How to make a service ==
	First, navigate to your mod's <code>Data>Script>[namespace]</code> folder. Once there, add a <code>services</code> folder if there isn't one already and, inside of it, create yet another folder. This final folder can have any name you want as long as it has no special characters in it, but it's best to stick to something that is as close as possible to the name you want to give to your service. For example, the base game's DebugTools service is inside the debug_tools folder.		First, navigate to your mod's <code>Data>Script>[namespace]</code> folder. Once there, add a <code>services</code> folder if there isn't one already and, inside of it, create yet another folder. This final folder can have any name you want as long as it has no special characters in it, but it's best to stick to something that is as close as possible to the name you want to give to your service. For example, the base game's DebugTools service is inside the debug_tools folder.
	Finally, create a text file inside of this folder and call it init.lua. Make sure that .lua is part of the file's extension and not still a portion of its name.		Finally, create a text file inside of this folder and call it init.lua. Make sure that .lua is part of the file's extension and not still a portion of its name.
Line 29:		Line 29:
	What we need to use to make a service work, however, is the Subscribe function. This is the function responsible for registering callbacks so that the game knows to call them whenever a specific event takes place. You can find a list of all Engine Events present in the game and their parameters [[Service Events\|here]].		What we need to use to make a service work, however, is the Subscribe function. This is the function responsible for registering callbacks so that the game knows to call them whenever a specific event takes place. You can find a list of all Engine Events present in the game and their parameters [[Service Events\|here]].

	==== Creating a Callback ====		=== Creating a Callback ===
	The first thing we need is the function we want to call. This can have any name you like, but it's best if its name references the event it is subscribed to in some way.<br>		The first thing we need is the function we want to call. This can have any name you like, but it's best if its name references the event it is subscribed to in some way.<br>
	We will use this simple print function as an example. Make sure to put it below your service's declaration but before its Subscribe function:		We will use this simple print function as an example. Make sure to put it below your service's declaration but before its Subscribe function:
Line 45:		Line 45:
	If you run the game now, you will notice that nothing happens still. This is because this file has never been loaded by the game. To make it load, create a <code>main.lua</code> file in your mod's <code>Data>Script>[namespace]</code> folder and write <code>require "[namespace].services.[service_folder]"</code> in it. Now the game will know it needs to load your service and you will see its OnInit function being called as expected.		If you run the game now, you will notice that nothing happens still. This is because this file has never been loaded by the game. To make it load, create a <code>main.lua</code> file in your mod's <code>Data>Script>[namespace]</code> folder and write <code>require "[namespace].services.[service_folder]"</code> in it. Now the game will know it needs to load your service and you will see its OnInit function being called as expected.

	==== Callbacks with parameters ====		=== Callbacks with parameters ===
	Many events contain parameters that get sent alongside their service messages so that services can reference and interact with them. These parameters are packaged into an argument array with starting index 0. An example of this is LossPenalty, whose argument 0 is the current GameProgress instance, which is to say, the save data itself. We need to pass this parameter along if we want to make use of it.<br>		Many events contain parameters that get sent alongside their service messages so that services can reference and interact with them. These parameters are packaged into an argument array with starting index 0. An example of this is LossPenalty, whose argument 0 is the current GameProgress instance, which is to say, the save data itself. We need to pass this parameter along if we want to make use of it.<br>
	If you're wondering what that first, discaded parameter is, it's your service's class. At no point you'll ever need this, since you're already working with it anyway.		If you're wondering what that first, discaded parameter is, it's your service's class. At no point you'll ever need this, since you're already working with it anyway.