Overview

Introduction

Recycling is a broad and complicated topic, but is very important both for performance and for logic.

Essentially, it controls when actors are "active" (actively moving, colliding, animating and performing logic) versus "dormant" (waiting invisibly and passively on the map for the camera to get close to them).

Actors that are active are slower and more memory consuming than actors that are dormant, which is why the maximum amounts of each can be set separately. Without recycling, actors that are on the far side of a massive level will be consuming CPU processes even when the player has no way to see or interact with them.

When is an actor set to a dormant state (recycled)?

For an actor to be made dormant, two conditions need to be true:

1. The actor is sufficiently far from the game display (outside of the recycle window).
2. The actor fails to render (the animation frame is invisible or entirely off screen).

(Or, alternatively, the actor is destroyed with the recycle after destroy flag is set).

The first condition is important in order to make sure that an actor is not constantly switching between active and dormant states.

The second condition is important to ensure that something large, like a boss, will not get recycled if part of the animation frame is on screen.

When is an actor set to an active state (unrecycled)?

For actor an actor to be made active, two conditions need to be true:

1. If the actor was recycled previously, it needs to have been outside of the spawn window for at least one frame. (This prevents an actor from spawning in the middle of the game window if the actor was set to respawn at the original position and the original position happens to be on screen).
2. The actor is now in the spawn window.

If an actor has never been set to an active state before, the OnSpawn code is run.

Where does an actor recycle to?

An actor will always recycle to the position stored in the actor_origin_x and actor_origin_y variables. The initial value of these variables are where the actor was when it first spawned.

You could manipulate these to have an actor respawn in a place that they did not originally spawn from, for example to ambush the player from a random part of the level. If "Recycle to original position" is set, the actor will always assume the original position was actor_origin_x and actor_origin_y even if you have manually changed it.

The actor_origin_x and actor_origin_y variables will be set to the actor's position when they are recycled, except when the "Recycle to original position" flag is set.

Do a lot of dormant actors slow Scorpion down the same way a lot of active actors do?

Generally not. Scorpion maintains a list of four "trip wires" for above, below, to the left and to the right of the screen.

When a camera crosses one of these trip wires, all dormant actors are now checked, and:

1. If the actor is close enough, the actor is made active.
2. If the actor is not close enough, the tripwires are repositioned so the check will be repeated when the actor could be close enough.

Essentially, the trip wire system means that Scorpion doesn't check the list from frame to frame, but only when the camera has tripped one of those wires.

Recycling modes

Each actor can only have one mode for recycling.

Always

The recycling mode works as usual. Actors will be made dormant once they're outside of the recycle window. This is the recommended default for most actors.

Default

Scorpion will pick a recycling mode for you based on the other settings of the actor (eg, selecting Never for players, Trash for projectiles and Always for most other things).

Never

The recycling system is completely turned off. This is only recommended for players and UI elements.

Actors set to never recycle can still be recycled if they're destroyed and Recycle after Destroy is set.

Trash

Actors are destroyed rather than recycled. This is primarily recommended for temporary actors like bullets or particles.

There is a use case where this is also recommended for regular actors. In a game that only scrolls in one direction, like 1942, it's best to simply trash enemies that leave the screen rather than use up the memory allocated for dormant actors (which is still limited).

Put another way - if you don't need to see an actor again after it's off screen, trash is the way to go.

Recycling flags

All recycling flags can be enabled or disabled independent of each other.

Flag	Description
Recycle after Destroy	Whenever an actor is triggered to be destroyed, they're actually recycled. This could allow an enemy to be repeatedly brought back to life in a level when the player leaves the screen.
Recycle to original pos	By default, actors recycle to the position that they last were when the camera scrolled away. This will ensure they recycle to their original spawn position instead.
OnSpawn after Recycle	The OnSpawn codeblock is run every single time an actor comes back into view

In addition, there are some flags that are not specific to recycling, but can influence recycling.

Flag	Description
Auto clear children	Will ensure that all child actors of this actor are destroyed if the actor is destroyed or recycled. This can be used with OnSpawn after recycle to ensure all child actors are destroyed and respawned.
Spawn at start	This means that an actor is not in a dormant state at start of the level. They may immediately go back into a dormant state if they happen to be far from the camea.

Spawn window

The spawn window is a rectangle that contains the camera display and an area around it. This controls how close the camera can be to an actor before it spawns.

The spawn window is controlled by four variables.

Variable	Default	Description
spawnarea_x	-16	The offset of the spawn window from the left of the camera
spawnarea_y	-16	The offset of the spawn window from the top of the camera
spawnarea_width	xres+32	The width of the spawn window
spawnarea_height	yres+32	The height of the spawn window

Here is an example that increases the spawn area by 20 pixels on the X Axis, but decreases the spawn area by 10 pixels on the Y Axis

spawnarea_x = spawnarea_x - 10
spawnarea_width = spawnarea_width + 20
spawnarea_y = spawnarea_y + 5
spawnarea_height = spawnarea_height - 10

Recycle window

The recycle window is a rectangle that contains the spawn window and an area around it. Actors that leave this window are prone to being recycled, assuming their animation frames are also not on screen. The reason this is slightly larger than the spawn window itself is to prevent a situation where an actor just on the edge will constantly be recycled and unrecycled.

Currently, the actor recycle window is controlled by a single variable called RecycleDistance which is set to a value of 16 by default. Increasing or decreasing the size of the recycle window is simply a case of changing that variable.