Difference between revisions of "Lua/DynamicEntitySpawning"

From Serious Sam Wiki
< Lua
Jump to: navigation, search
m (Guess what? Yeah, formatting.)
m (Fixed missing code formatting.)
Line 31: Line 31:
 
ResolveResource() is no longer necessary, as LoadResource() automatically does this now. The functions used to spawn entities have also be condensed slightly:
 
ResolveResource() is no longer necessary, as LoadResource() automatically does this now. The functions used to spawn entities have also be condensed slightly:
  
 +
<pre>
 
local TemplateProvider = LoadResource("[Filepath To Template Provider]")<br>
 
local TemplateProvider = LoadResource("[Filepath To Template Provider]")<br>
 
TemplateProvider:SpawnEntityFromTemplate(0, worldInfo, Placement)
 
TemplateProvider:SpawnEntityFromTemplate(0, worldInfo, Placement)
 +
</pre>
  
 
== Example ==
 
== Example ==

Revision as of 20:58, 12 November 2018


Overview

The engine allows to spawn entities right during the game, thanks to scripting. There are three steps to do that:

1) Creating a template properties holder.

This is simply a special kind of a resource which can be created in the Editor, using the Create Dialog (Ctrl+N) and selecting 'Generic / Template properties holder'. In essence, the template holder is a container of entity properties, which can freely be added and edited using all the available Editor tools. These properties will be accessible through the holder's script interface.


2) Loading the template properties holder resource in a script.

Once the template properties holder resource has been created and saved, it is ready to be used by scripts. To turn your template properties into actual object you have to create a new variable to hold your resource by using global function LoadResource(filePath).

Example: local TemplateProvider = LoadResource("Content/MyProject/Databases/DynSpawnTemp/MyTemplate.rsc")


3) Spawning an entity.

To spawn your template, you have to call function SpawnEntityFromTemplate() on TemplateProvider. In that call you should provide ID of resource to be extracted from template, worldInfo and placement (quaterion).

Example: TemplateProvider:SpawnEntityFromTemplate(0, worldInfo, Placement)

After that you will see your entity (specified in loaded resource) spawned at specified position.

Changes since SED2017

ResolveResource() is no longer necessary, as LoadResource() automatically does this now. The functions used to spawn entities have also be condensed slightly:

local TemplateProvider = LoadResource("[Filepath To Template Provider]")<br>
TemplateProvider:SpawnEntityFromTemplate(0, worldInfo, Placement)

Example

Here is a minimal but complete example showing all the above steps. We'll assume a template properties holder had been created with a single shaker effect properties.

local eePlayerBorn = Wait(Event(worldInfo.PlayerBorn)) -- eePlayerBorn : CPlayerBornScriptEvent
local player = eePlayerBorn:GetBornPlayer() -- player : CPlayerPuppetEntity

local TemplateProvider = LoadResource("Content/SeriousSam3/Examples/templates.rsc")
local shaker = TemplateProvider:SpawnEntityFromTemplate(0, worldInfo, player:GetPlacement()) -- shaker : CShakerEffectEntity
shaker:StartShaking()       

Outdated tutorial (SE4 and less)

Outdated tutorial (for SE4 and less)

Overview.

There are three steps required for spawning entities on the fly through scripts:

1) Creating a template properties holder.

This is simply a special kind of a resource which can be created in the Editor, using the Create Dialog (Ctrl+N) and selecting 'Generic / Template properties holder'. In essence, the template holder is a container of entity properties, which can freely be added and edited using all the available Editor tools. These properties will be accessible through the holder's script interface.


2) Loading the template properties holder resource in a script.

Once the template properties holder resource has been created and saved, it is ready to be used by scripts. Scripts can obtain resources using the LoadResource() function on the global worldInfo object. However, this function will return a smart pointer, which is just a wrapper used for automatic memory management. Therefore, for each use, the smart pointer must be resolved into the actual object using the global function ResolveResource().


3) Creating a local properties object, setting it up, and spawning an entity.

The template holder offers two simple functions: CreateTemplate() and SpawnEntity(). The first function creates a local properties object by cloning one of the predefined properties stored in the resource (which can be selected by its index). Then, these local properties can be modified in any way - most likely, setting the correct placement, at least. Once the setup is complete, calling SpawnEntity() will actually create the new entity. Note: it is perfectly legal to call SpawnEntity() multiple times using the same properties, in order to spawn multiple entities.


Example.

Here is a minimal but complete example showing all the above steps. We'll assume a template properties holder had been created with a single shaker effect properties.

local eePlayerBorn = Wait(Event(worldInfo.PlayerBorn)) -- eePlayerBorn : CPlayerBornScriptEvent
-- player : CPlayerPuppetEntity 
local player = eePlayerBorn:GetBornPlayer() 

local ptrTemplates = worldInfo:LoadResource("Content/SeriousSam3/Examples/templates.rsc")
-- templates : CTemplatePropertiesHolder 
local templates = ResolveResource(ptrTemplates) 

local shakerProperties = templates:CreateTemplate(0)
-- shaker : CShakerEffectEntity
shakerProperties:SetPlacement(player:GetPlacement()) 
local shaker = templates:SpawnEntity(worldInfo:GetWorld(), shakerProperties)
shaker:StartShaking()       


Special Notes

Info 16x16.png Note: Be mindful of whether your script code is being executed on the server or on a client. Local effects (particles, shakers, shockwaves, etc) can be spawned by both server and clients. However, entities which require synchronization through network (such as puppets) should only be spawned on the server, as clients will automatically create them as they receive updates from the server.

Info 16x16.png Note: Scripts from SE4 and less have to be updated to support the new system in SE2017+.