Jazz2::Actors::ActorBase class
#include <Jazz2/Actors/ActorBase.h>

Base class of an object.

Common base of every object that lives in the game world. It provides the shared lifecycle and behavior of an actor: activation from the event map, per-frame update, movement and collisions (with tiles, other actors and solid objects), rendering and light emission, and health and perishing. Concrete actors derive from it and override the relevant virtual callbacks.

Derived classes

class CollectibleBase
Base class of a collectible object.
class GemGiant
Giant gem.
class EnemyBase
Base class of an enemy.
class AirboardGenerator
Airboard generator.
class AmbientBubbles
Ambient bubbles.
class AmbientSound
Ambient sound.
class Bird
Bird.
class Bomb
Bomb.
class BonusWarp
Bonus warp.
class Checkpoint
Checkpoint.
class Copter
Copter.
class EndOfLevel
End of level sign.
class Eva
Eva.
class IceBlock
Ice block.
class Moth
Moth.
class Spring
Spring.
class SteamNote
Steam note.
class SwingingVine
Swinging vine.
class Explosion
Explosion effects.
class FlickerLight
Flickering light.
class PulsatingRadialLight
Pulsating radial light.
class StaticRadialLight
Static radial light.
class CtfBase
Capture The Flag base.
class Flag
Capture The Flag flag/base marker.
class RemoteActor
Remote object in online session.
class Player
Represents a controllable player.
class PlayerCorpse
Represents a dead corpse of a player.
class Bridge
Bridge.
class Pole
Pole.
class SolidObjectBase
Base class of a (pushable) solid object.
class ShotBase
Base class of a shot from a player's weapon.
class TNT
TNT.
class Jazz2::Scripting::ScriptActorWrapper
Wraps a scripted actor, forwarding engine callbacks to the AngelScript object.

Constructors, destructors, conversion operators

ActorBase()
Creates a new instance.
~ActorBase() virtual

Public functions

auto IsFacingLeft() const -> bool
Returns true if the object is currently facing left.
auto OnActivated(const ActorActivationDetails& details) -> Task<bool>
Called after the object is created.
auto OnHandleCollision(ActorBase* other) -> bool virtual
Called when the object collides with another object.
auto CanCauseDamage(ActorBase* collider) -> bool virtual
Called to check whether collider can cause damage to the object.
auto IsInvulnerable() -> bool
Returns true if the object is invulnerable.
auto GetHealth() -> std::int32_t
Returns current health.
void SetHealth(std::int32_t value)
Sets current health.
auto GetMaxHealth() -> std::int32_t
Returns maximum health.
void DecreaseHealth(std::int32_t amount = 1, ActorBase* collider = nullptr)
Decreases health by specified amount.
auto MoveInstantly(Vector2f pos, MoveType type, Tiles::TileCollisionParams& params) -> bool
Moves the object.
auto MoveInstantly(Vector2f pos, MoveType type) -> bool
void AddExternalForce(float x, float y)
Adds external force.
auto IsCollidingWith(ActorBase* other) -> bool
Returns true if this object is colliding with a given object.
auto IsCollidingWith(const AABBf& aabb) -> bool
Returns true if this object is colliding with a given AABB.
auto HasCrossedOver(const ActorBase* other) const -> bool
Returns true if this object crossed over a given object during the current frame.
void UpdateAABB()
Updates AABB for current position, rotation and animation frame.
void UpdateRendererPosition() virtual
Re-applies the current position to the renderer.
auto GetPos() -> Vector2f
Returns current position.
auto GetSpeed() -> Vector2f
Returns current speed.
auto GetState() const -> ActorState constexpr noexcept
Returns actor state.
auto GetState(ActorState flag) const -> bool constexpr noexcept
auto GetSpawnEventType() const -> EventType noexcept
Returns event type the object was spawned from, or EventType::Empty if it wasn't created from an event.

Public variables

AABBf AABB
Outer AABB hitbox.
AABBf AABBInner
Inner AABB hitbox.

Protected types

class ActorRenderer
Actor renderer.

Protected static functions

static void PreloadMetadataAsync(StringView path)
Preloads specified metadata and its linked assets to cache.

Protected functions

void SetParent(SceneNode* parent)
Sets internal parent node.
void SetFacingLeft(bool value)
Sets whether the object is facing left.
auto OnActivatedAsync(const ActorActivationDetails& details) -> Task<bool> virtual
Called when the object is created and activated.
auto OnTileDeactivated() -> bool virtual
Called when corresponding tile should be deactivated.
auto IsSerializable() const -> bool virtual
Returns true if the live state of the object can be stored in a level state snapshot.
void OnSerializeState(Stream& dest) virtual
Serializes the live state of the object to a level state snapshot.
void OnDeserializeState(Stream& src) virtual
Restores the live state of the object from a level state snapshot.
void OnAttach(ActorBase* parent) virtual
Called when the object is attached to an another object.
void OnDetach(ActorBase* parent) virtual
Called when the object is detached from the previously attached object.
void OnHealthChanged(ActorBase* collider) virtual
Called when health of the object changed.
auto OnPerish(ActorBase* collider) -> bool virtual
Called when the object has no health left and should perish.
void OnUpdate(float timeMult) virtual
Called every frame to update the object state.
void OnUpdateHitbox() virtual
Called when the hitbox needs to be updated.
auto OnDraw(RenderQueue& renderQueue) -> bool virtual
Called when the object needs to be drawn.
void OnEmitLights(SmallVectorImpl<LightEmitter>& lights) virtual
Called when emitting lights.
void OnEmitRemotedLights(SmallVectorImpl<LightEmitter>& lights) virtual
Called when emitting lights that have to be replicated to remote peers.
auto IsIlluminatedStateRemoted() const -> bool virtual
Whether an observer reproduces this object's ActorState::Illuminated decoration itself.
void OnHitFloor(float timeMult) virtual
Called when the object hits a floor.
void OnHitCeiling(float timeMult) virtual
Called when the object hits a ceiling.
void OnHitWall(float timeMult) virtual
Called when the object hits a wall.
auto GetGravityModifier(float baseGravity, bool isRising) const -> float virtual
Returns the gravity applied this frame, allowing it to be direction-dependent (e.g., the player's asymmetric jump arc).
void OnTriggeredEvent(EventType eventType, std::uint8_t* eventParams) virtual
Called when an event is triggered.
void TryStandardMovement(float timeMult, Tiles::TileCollisionParams& params)
Performs standard movement behavior.
void ResetPathTracking()
Discards the path the object travelled so far during the current frame.
auto TryUnstuck() -> bool
Tries to push the actor out of solid geometry it ended up inside of.
void UpdateHitbox(std::int32_t w, std::int32_t h)
Updates hitbox to a given size.
void UpdateFrozenState(float timeMult)
Updates frozen state of the object.
void HandleFrozenStateChange(ActorBase* shot)
Handles change of frozen state after collision with other object.
void CreateParticleDebrisOnPerish(ActorBase* collider)
Creates a particle debris from a sprite when the object is going to perish.
void CreateParticleDebrisOnPerish(ParticleDebrisEffect effect, Vector2f speed)
void CreateSpriteDebris(AnimState state, std::int32_t count)
Creates a sprite debris.
auto GetIceShrapnelScale() const -> float virtual
Returns scale of ice shrapnels.
auto PlaySfx(StringView identifier, float gain = 1.0f, float pitch = 1.0f) -> std::shared_ptr<AudioBufferPlayer>
Plays a sound effect for the object.
auto SetAnimation(AnimState state, bool skipAnimation = false) -> bool
Sets an animation of the object.
auto SetTransition(AnimState state, bool cancellable, Function<void()>&& callback = {}) -> bool
Sets a transition animation of the object.
void CancelTransition()
Cancels a cancellable transition.
void ForceCancelTransition()
Cancels any transition.
void OnAnimationStarted() virtual
Called when an animation started.
void OnAnimationFinished() virtual
Called when an animation finished.
void OnPacketReceived(MemoryStream& packet) virtual
Called when the object receives a network packet.
void SendPacket(ArrayView<const std::uint8_t> data)
Sends a packet to the other side of a non-local session.
void RequestMetadata(StringView path, bool forceIndexed = false)
Loads specified metadata and its linked assets.
void RequestMetadataAsync(StringView path, bool forceIndexed = false)
Loads specified metadata and its linked assets asynchronously if supported.
void SetState(ActorState flags) constexpr noexcept
Sets actor state.
void SetState(ActorState flag, bool value) constexpr noexcept

Constants

static std::uint8_t AlphaThreshold protected constexpr
Alpha transparency threshold — the same one the collision masks are built with.
static float CollisionCheckStep protected constexpr
Step for collision checking.
static float MaxMovementStep protected constexpr
Longest distance resolved by a single collision sub-step of TryStandardMovement().
static std::int32_t MaxMovementSubsteps protected constexpr
Upper bound on collision sub-steps performed by TryStandardMovement() in a single frame.
static float MaxUnstuckDistance protected constexpr
Farthest TryUnstuck() displaces an actor to get it out of solid geometry.
static float UnstuckRetryNotStuck protected constexpr
Frames before TryUnstuck() probes again after finding the actor was not stuck at all.
static float UnstuckRetryTrapped protected constexpr
Frames before TryUnstuck() searches again for an actor it found no way out for.
static float UnstuckCooldown protected constexpr
Frames before TryUnstuck() runs again for an actor it successfully freed.
static std::int32_t PerPixelCollisionStep protected constexpr
Step for per-pixel collisions.
static std::int32_t AnimationCandidatesCount protected constexpr
Maximum number of animation candidates.
static std::int32_t SpawnParamsSize protected constexpr
Size of event parameters the object was spawned with, the same as Events::EventSpawner::SpawnParamsSize.

Function documentation

bool Jazz2::Actors::ActorBase::MoveInstantly(Vector2f pos, MoveType type)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool Jazz2::Actors::ActorBase::HasCrossedOver(const ActorBase* other) const

Returns true if this object crossed over a given object during the current frame.

IsCollidingWith() only compares the two objects where they ended up, so a fast object can pass a small one between two frames without ever overlapping it - the faster the object and the lower the frame rate, the more likely that is. This tests the path the object took instead, and only for movement long enough to clear the other object in a single step, so it can only ever report a hit that was missed.

void Jazz2::Actors::ActorBase::UpdateRendererPosition() virtual

Re-applies the current position to the renderer.

Called automatically after the object updates itself. It has to be called again for an object that is moved by something else afterwards (a platform carrying it, for instance), otherwise it would be drawn where it was before that move for one frame. An object that is drawn somewhere else than where it is simulated (a server-side shadow of a remote player showing its interpolated position) overrides this instead of assigning the position to the renderer on its own.

bool Jazz2::Actors::ActorBase::GetState(ActorState flag) const constexpr noexcept

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool Jazz2::Actors::ActorBase::IsSerializable() const virtual protected

Returns true if the live state of the object can be stored in a level state snapshot.

A snapshot stores the event type and parameters the object was spawned with together with its live state, so the object can be spawned again and resurrected exactly as it was. That works only for objects spawned from an event (see ActorActivationDetails::Type) which is registered in Events::EventSpawner. Objects that are not worth restoring (e.g., short-lived effects) can opt out by overriding it.

void Jazz2::Actors::ActorBase::OnSerializeState(Stream& dest) virtual protected

Serializes the live state of the object to a level state snapshot.

Called only if IsSerializable() returns true. Anything that is initialized from the event parameters in OnActivatedAsync() doesn't need to be stored, because the object is spawned again with the same parameters before OnDeserializeState() is called. Derived classes must call the base implementation first and read the data back in the same order.

void Jazz2::Actors::ActorBase::OnDeserializeState(Stream& src) virtual protected

Restores the live state of the object from a level state snapshot.

Called right after the object was spawned again (i.e., after OnActivatedAsync()) and before it's added to the level. Running transitions are not restored, because their callbacks cannot be serialized, so derived classes have to put the object into a state that doesn't wait for such a callback.

void Jazz2::Actors::ActorBase::OnEmitRemotedLights(SmallVectorImpl<LightEmitter>& lights) virtual protected

Called when emitting lights that have to be replicated to remote peers.

An object simulated on a multiplayer server is drawn on the clients by a stand-in that runs none of its logic, so the lights it emits have to be described to them explicitly. This defaults to OnEmitLights(), which is right for anything whose lighting belongs to the object itself.

Overriding it describes only the part that every observer must see. Lights that a client already produces on its own — decoration driven by a local preference, or an object whose stand-in replays the whole effect — are left out, so they aren't sent (and applied) twice.

bool Jazz2::Actors::ActorBase::IsIlluminatedStateRemoted() const virtual protected

Whether an observer reproduces this object's ActorState::Illuminated decoration itself.

ActorState::Illuminated is a generic per-event flag (see Events::EventMap::ReadEvents()), so it may only be remoted for an object that actually turns it into lights — an observer would otherwise glow for an event that emits nothing on the server. An object that answers true leaves those lights out of OnEmitRemotedLights() and lets every observer seed an equivalent swarm locally, which is far cheaper than describing two dozen constantly moving lights on every update.

Declared here rather than tested for by type in the packet builder, so adding another such object is a matter of overriding this and nothing else has to know the class exists.

void Jazz2::Actors::ActorBase::ResetPathTracking() protected

Discards the path the object travelled so far during the current frame.

The swept collision tests treat the distance between the position the object had when the frame started and its current position as a path it physically travelled, so everything along that line is checked as well (see HasCrossedOver()). A forced relocation — a warp, a respawn, a multiplayer re-sync — covers the distance without passing through anything in between, so the path has to be discarded, otherwise the object would collect, hit or trigger everything on the straight line to its destination. MoveInstantly() does this on its own for every absolute move, only code assigning the position directly has to call it.

bool Jazz2::Actors::ActorBase::TryUnstuck() protected

Tries to push the actor out of solid geometry it ended up inside of.

Returns true if the actor was moved to a free position

Probes with its own non-destructive collision parameters, so neither the check nor the search for a free spot can destroy a tile or count as a weapon hit.

void Jazz2::Actors::ActorBase::CreateParticleDebrisOnPerish(ParticleDebrisEffect effect, Vector2f speed) protected

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void Jazz2::Actors::ActorBase::RequestMetadata(StringView path, bool forceIndexed = false) protected

Loads specified metadata and its linked assets.

Parameters
path Relative path to the metadata asset
forceIndexed Load linked graphics as indexed (for shader-based recoloring, e.g., the player)

void Jazz2::Actors::ActorBase::SetState(ActorState flag, bool value) protected constexpr noexcept

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.