Shrapnel - alexneargarder/Broforce-Docs GitHub Wiki

Shrapnel

Table of Contents

Unity Lifecycle & Setup

Methods

protected virtual void Awake()

Initializes the shrapnel object when created or resurrected from the object pool. Sets up sprite references, caches original sprite values for restoration, initializes random seeds and z-depth offsets, and configures initial gravity and bounce settings. This method handles both fresh instantiation and pool resurrection scenarios.

public virtual void EffectDie()

Handles the death of this shrapnel by attempting to return it to the object pool. If pooling is not available or fails, destroys the GameObject entirely. This is the primary cleanup method called when shrapnel expires.

public virtual void EffectFirstUpdate()

Performs first-frame initialization for pooled effects. Registers with the ShrapnelManager for performance optimization through timeslicing, sets up physics layer masks, initializes see-saw motion parameters with random offsets, and applies any pending color changes. This ensures proper setup regardless of how the object was created.

public virtual void EffectResurrect()

Resurrects this shrapnel from the object pool, resetting all properties to their initial states. Clears motion values, resets sprite dimensions, removes parented transform references, and re-invokes Awake for fresh initialization. This enables efficient object pooling by fully resetting the instance.

protected virtual void Start()

Called when the shrapnel first becomes active. Delegates initialization to EffectFirstUpdate for proper setup of pooled effect systems.

Properties

public bool DoneFirstUpdate { get; set; }

Gets or sets whether this effect has completed its first update cycle after being resurrected from an object pool. Used by the pooling system to ensure one-time initialization logic runs only once per resurrection. Set to false when ResurrectForPool is called, and automatically set to true by FirstUpdateFromPool. Part of the IPoolableEffect interface implementation.

public EffectPool ParentPool { get; set; }

Gets or sets the EffectPool instance that manages this pooled effect. Null when the effect is not pooled. Set by ResurrectForPool when retrieving from a pool. Used to return the effect back to its originating pool when it dies, avoiding garbage collection. Part of the IPoolableEffect interface implementation.

public int PoolIndex { get; set; }

Gets or sets the index position of this effect within its parent object pool. Set to -1 when the effect is not part of a pool or has been removed from pooling. Used by the pooling system to efficiently manage and return effects to their designated pool slots. Part of the IPoolableEffect interface implementation.

public virtual bool ShouldTimeslice { get; set; }

Gets whether this shrapnel should participate in timeslicing for performance optimization. Default returns true, allowing the ShrapnelManager to skip updates on some frames when many particles are active. Override to false for critical effects that must update every frame.

Fields

public int timesliceIndex

Unique index assigned by ShrapnelManager for timeslicing optimization. Used to distribute update calls across multiple frames when many shrapnel particles are active, improving performance by updating only a subset each frame.

Position & Physics

Methods

protected virtual void ApplyGravity()

Applies downward acceleration to vertical velocity based on gravity settings and time delta. Uses curGravity multiplier which can be modified for different gravity effects (e.g., in quicksand).

protected virtual void Bounce(bool bounceX, bool bounceY)

Handles physics response when colliding with surfaces. Applies bounce multipliers to reverse velocity, adds friction, reduces lifetime and rotation speed. Can trigger death effects, blood splashes, or gradual life loss based on configuration flags.

Parameters:

  • bool bounceX: Whether horizontal bounce occurred
  • bool bounceY: Whether vertical bounce occurred

protected virtual void CheckWallCollisions(ref bool bounceY, ref bool bounceX, ref float yIT, ref float xIT)

Checks for collisions with terrain blocks and handles bouncing or constraint logic. Also manages parenting to moving platforms when moveWithRestingTransform is enabled. Updates bounce flags and adjusts position/velocity based on collision results.

Parameters:

  • out bool bounceY: Output flag indicating vertical bounce occurred
  • out bool bounceX: Output flag indicating horizontal bounce occurred
  • out float yIT: Reference to vertical movement delta, modified if constrained
  • out float xIT: Reference to horizontal movement delta, modified if constrained

public virtual void Launch(float x, float y, float xI, float yI, float _rI)

Launches the shrapnel from a specific position with initial velocity. Sets position, applies velocity with random variations, calculates lifetime with randomization, initializes rotation based on horizontal velocity, and configures sprite shrinking rates. If shrapnelControlsMotion is false, creates a Rigidbody for Unity physics simulation.

Parameters:

  • float x: Initial X position in world coordinates
  • float y: Initial Y position in world coordinates
  • float xI: Initial horizontal velocity
  • float yI: Initial vertical velocity

public virtual void Launch(float x, float y, float xI, float yI, float _rI)

Launches the shrapnel with explicit rotation speed control. Similar to the 4-parameter version but allows direct specification of rotation speed rather than calculating it from velocity. Used when precise rotation control is needed.

Parameters:

  • float x: Initial X position in world coordinates
  • float y: Initial Y position in world coordinates
  • float xI: Initial horizontal velocity
  • float yI: Initial vertical velocity
  • float _rI: Initial rotation speed in degrees per second

protected virtual void RunMovement()

Executes physics movement for this frame, including drag application, velocity integration, wall collision detection, and position updates. Handles special cases like destruction inside walls and collision bouncing. Called by Update when shrapnelControlsMotion is true.

public virtual void SetPosition()

Updates the transform position and rotation based on current values. If rotateAtRightAngles is true or rotation speed is zero, snaps rotation to 90-degree increments and rounds position to integer values for pixel-perfect rendering. Otherwise applies smooth rotation and positioning.

Fields

private float _curRandomOnBounce

Current amount of random horizontal velocity applied on bounce. Initialized from xI_randomOnBounce and reduced after each bounce. Multiplied by 0.66 after each bounce application to create diminishing randomness over the shrapnel's lifetime.

public bool bloodSplashOnDeath

When true, creates a blood splash effect when the shrapnel bounces upward off the ground (yI > 0). Uses the bloodColor field to determine splash color. Also calls Death() if the shrapnel isn't already dead. Used for gore particles.

public float bounceM = 0.4f

The bounce multiplier that controls velocity retention after impacts. Default value is 0.4 (40% velocity retention). Applied differently for horizontal bounces (multiplied by 1.5) versus vertical bounces to create realistic bounce behavior.

public bool collidesWithWalls = true

Whether this shrapnel checks for and responds to collisions with walls and ground. When true, performs collision detection each frame and bounces off surfaces. When false, passes through all terrain. Default is true.

protected float curGravity

The current gravity multiplier being applied to the shrapnel. Initialized from gravityM during Awake(). Used in ApplyGravity() to calculate downward acceleration, can be modified at runtime for special effects.

public bool deathOnBounce

When true, immediately destroys the shrapnel particle upon any collision bounce. Used for fragile particles that should shatter on impact. Calls Death() method when triggered.

public bool destroyInsideWalls = true

Controls whether the shrapnel is immediately destroyed when inside wall colliders. Default is true for automatic cleanup. Checked during RunMovement() to prevent shrapnel from getting stuck inside terrain.

public float drag

Air resistance factor applied to velocity each frame. When greater than 0, reduces both X and Y velocity by (velocity * drag * deltaTime). Used to simulate air friction and slow particles over time without using Unity's physics system.

public float frictionM = 1f

Friction multiplier applied to horizontal velocity when bouncing off the ground. Default value is 1.0. When the shrapnel bounces vertically, the X velocity is multiplied by (0.8 * frictionM) to simulate ground friction effects.

public float gravityM = 1f

Gravity strength multiplier for this shrapnel instance. Default value is 1.0 for normal gravity. Applied to the standard gravity acceleration of 500 units/second². Set to 0 for floating particles or values less than 1 for slower falling effects.

protected LayerMask groundLayer

Layer mask containing the ground collision layers (Ground and IndestructibleGround). Set during EffectFirstUpdate() and used for raycasting when moveWithRestingTransform is enabled to detect ground surfaces the shrapnel can parent to.

public float lifeLossM = 0.2f

The percentage of starting life lost when the shrapnel bounces, if lifeLossOnBounce is enabled. Default value is 0.2 (20% life loss per bounce). Applied in Bounce() method to gradually reduce the shrapnel's lifetime through repeated impacts.

public bool lifeLossOnBounce

Determines whether the shrapnel loses life when bouncing off surfaces. When true, bouncing reduces the shrapnel's life by a percentage of its start life. Works in conjunction with lifeLossM to control how much life is lost per bounce.

public bool moveWithRestingTransform

Enables the shrapnel to move with surfaces it lands on, such as moving platforms or vehicles. When true, CheckWallCollisions() performs raycasts to detect surfaces below and parents the shrapnel to them.

protected Collider parentedCollider

Reference to a collider that the shrapnel is currently resting on or attached to. Used for platform attachment mechanics. When set, the shrapnel moves with the collider's transform, allowing it to ride on moving platforms or objects.

protected Vector3 parentedPosition

Stores the position of the parented collider's transform when attachment occurs. Used to calculate relative movement. Updated in CheckWallCollisions() when the shrapnel lands on a surface with moveWithRestingTransform enabled.

public float r

Current rotation angle in degrees. Updated each frame by adding rI * deltaTime when shrapnelControlsMotion is true, creating spinning motion for debris particles.

public bool randomMotion

Enables chaotic random velocity changes each frame to simulate erratic particle movement. When true, adds random values between -6 and 6 (multiplied by randomMotionM) to both X and Y velocity, then applies damping to prevent excessive speed buildup.

public float randomMotionM = 1f

Multiplier for random motion intensity when randomMotion is enabled. Default is 1.0. Higher values create more erratic movement. Also affects the damping rate - velocity is multiplied by (1 - deltaTime * 2 * randomMotionM) each frame.

public float rI

Rotation speed in degrees per second. Set during Launch based on horizontal velocity direction, a random value, and the rotationSpeedMultiplier. Gradually reduced by bouncing impacts when configured.

public bool rotateAtRightAngles = true

When true, constrains rotation to 90-degree increments for pixel-art style rendering. Also enables position rounding to integer values for crisp pixel-perfect display. Default is true.

public float rotationSpeedMultiplier = 1f

Multiplier applied to the rotation speed when the shrapnel is launched. Used to scale the base rotation speed calculation. When Launch() is called, this multiplier is applied to the calculated rotation speed (200-500 units) to create varied spin effects.

protected float seeSawCounter

Internal counter that tracks the current phase of the see-saw oscillation. Incremented each frame by (deltaTime * seeSawSpeed) and used as input to sine functions for generating the swaying motion. Initialized with a random value between 0 and 100 to desynchronize multiple particles.

public bool seeSawFalling

Enables a pendulum-like swaying motion as the particle falls. When true, applies damping to velocity and adds sinusoidal horizontal movement based on fall speed. Creates a leaf-like or paper-like falling effect. Uses seeSawIntensity and seeSawSpeed to control the motion.

public float seeSawIntesity = 1f

Controls the horizontal swing amplitude when seeSawFalling is enabled. Default is 1.0. Applied as a multiplier to the base swing force of 300 units/second. Only affects horizontal movement when falling speed exceeds -8 units/second.

protected float seeSawSpeed = 1f

Controls the oscillation frequency of see-saw falling motion. Initialized to a random value between 8 and 13 in EffectFirstUpdate(). Higher values create faster swaying. Used to increment the seeSawCounter each frame.

public bool shrapnelControlsMotion = true

Determines whether the shrapnel class controls movement directly (true) or delegates to Unity's Rigidbody physics (false). When false, a Rigidbody component is added during Launch() for realistic physics simulation, commonly used for grenades.

public float size = 3f

Collision size radius for the shrapnel particle in world units. Used for wall collision detection and determining when the shrapnel is inside walls. Also used to set the box collider size when using Unity's Rigidbody physics (size * 2 + 2 units).

public float xI_randomOnBounce

The maximum horizontal velocity variation applied when bouncing. Controls how much random horizontal movement is added after impacts. Copied to _curRandomOnBounce during Awake() and reduced by 66% after each bounce for diminishing randomness.

public float zOffset

The Z-axis offset for positioning the shrapnel in 3D space. Initialized with a small random value (0-0.05) to create visual depth variation. Applied to transform.position.z in SetPosition() to prevent z-fighting when multiple shrapnel overlap.

Animation & Sprite Systems

Methods

public void SetColor(Color shrapnelColor)

Sets the sprite color for this shrapnel. If called before first update, the color is cached and applied during initialization to ensure it persists through pooling operations.

Parameters:

  • Color shrapnelColor: The color to apply to the sprite renderer

Fields

private Color _originalSpriteColor = Color.white

Stores the original color of the sprite component before any modifications. Default is Color.white. Cached during Awake() and used to restore the sprite to its original appearance during resurrection.

private float _originalSpriteDimY = 2f

Stores the original Y pixel dimension of the sprite. Default is 2.0. Used to set spritePixelHeight for UV-based fade animations where different sprite regions represent decay stages.

private float _originalSpriteHeight = 1f

Stores the original height of the sprite before any scaling effects. Default is 1.0. Used alongside _originalSpriteWidth to maintain the sprite's original aspect ratio during resurrection.

private float _originalSpriteWidth = 1f

Stores the original width of the sprite before any scaling effects. Default is 1.0. Used to restore the sprite to its original size when the shrapnel is resurrected from the object pool.

private bool _spriteValuesCached

Tracks whether the original sprite values have been cached. Prevents redundant caching of sprite properties. Set to true after first caching _originalSpriteColor, width, height, and dimY values during Awake().

public bool fades

When true, the sprite's alpha transparency fades from fully opaque to fully transparent over the particle's lifetime. Calculates alpha as (life / startLife). Used for particles that should gradually disappear rather than vanishing instantly.

public bool fadeUVs

When true, cycles through different UV coordinates on the sprite sheet based on remaining lifetime. Uses spritePixelHeight to offset UV coordinates in 4 stages: full brightness at 80%+ life, then progressively darker frames at 60%, 30%, and below 30% life remaining.

public float lifeM = 1f

Base lifetime multiplier for the shrapnel particle. Default is 1.0. Applied to the calculated lifetime in Launch() methods. Higher values make particles last longer before being destroyed. Final lifetime is (base time + random variation) * lifeM.

public float randomLifeM = 1f

Controls the amount of random variation in particle lifetime. Default is 1.0. In the 4-parameter Launch(), adds random variation between -0.5 and 0.5 seconds multiplied by this value. Helps create more natural-looking particle effects by varying lifespans.

protected bool setColorAtStart

Flag indicating whether a custom color was set via SetColor() that should be reapplied after pooling resurrection. This field is set to true when SetColor() is called, reset to false during EffectResurrect(), and checked during EffectFirstUpdate() to restore the custom color. This mechanism ensures that shrapnel particles maintain their intended color even when recycled from the object pool system.

public bool shrink = true

When true, the sprite gradually shrinks to zero size over the particle's lifetime. Uses spriteWidthI and spriteHeightI to calculate the shrink rate. Default is true. Creates a dissolving or disintegrating visual effect.

protected SpriteSM sprite

Reference to the SpriteSM component used for rendering the shrapnel's visual appearance. Cached during Awake() and used throughout the lifecycle for color changes, size adjustments, and UV animation.

protected float spriteHeight = 2f

Current height of the sprite in world units. Initialized from the sprite component's height in Launch() and modified over time when shrink is enabled. Used to dynamically resize the visual representation of the shrapnel particle.

protected float spriteHeightI

Rate of height change per second when shrink is enabled. Calculated as (-spriteHeight / life) to ensure the sprite reaches zero size when the particle dies. Applied each frame as (spriteHeightI * deltaTime) to gradually shrink the particle.

protected int spritePixelHeight = 2

Height of each sprite frame in pixels on the texture atlas. Used with fadeUVs to calculate UV coordinate offsets for displaying different animation frames. Initialized from the sprite's pixel dimensions in Awake(). Default is 2 pixels.

protected float spriteWidth = 2f

Current width of the sprite in world units. Initialized from the sprite component's width in Launch() and modified over time when shrink is enabled. Used to dynamically resize the visual representation of the shrapnel particle.

protected float spriteWidthI

Rate of width change per second when shrink is enabled. Calculated as (-spriteWidth / life) to ensure the sprite reaches zero size when the particle dies. Applied each frame as (spriteWidthI * deltaTime) to gradually shrink the particle.

Core System

Methods

public virtual void Death()

Marks the shrapnel as dead and triggers cleanup through EffectDie. Can be called directly or via RPC for networked destruction. Sets isDead flag to prevent multiple death calls.

public void ForceDeathRPC()

Sends a network RPC to destroy this shrapnel on all connected clients. Ensures synchronized particle removal in multiplayer scenarios.

protected virtual void RunLife()

Decrements lifetime by frame delta and triggers Death when expired. Simple countdown system that ensures shrapnel doesn't persist indefinitely, maintaining performance and visual clarity.

protected bool ShouldRunThisFrame()

Determines if this shrapnel should update this frame based on timeslicing optimization. When many particles are active, distributes updates across multiple frames to maintain performance. Always updates timesliceIndex counter for proper distribution.

protected virtual bool Update()

Main update loop handling all shrapnel behavior. Performs timeslicing checks, calculates time delta with compensation, handles both manual and Rigidbody physics, applies various motion effects (gravity, drag, see-saw, quicksand), manages sprite effects (fading, UV animation, shrinking), and checks lifecycle conditions. Returns false if skipped due to timeslicing.

Properties

public virtual bool ShouldKillIfNotVisible { get; set; }

Gets or sets whether this shrapnel should automatically die when it moves off-screen. Defaults to true in Awake for performance optimization. When true, checks visibility in Update using SortOfFollow.IsItSortOfVisible with a 48x48 pixel buffer zone. If not visible and life > 0, immediately sets life to -0.1f to trigger death. Can be overridden (e.g., set to false for cutscene effects that need to persist off-screen).

Fields

private ShrapnelManager _shrapnelManager

Cached reference to the global ShrapnelManager singleton that manages timeslicing and pooling for performance. Retrieved during EffectFirstUpdate() and used to register this shrapnel instance and access timeslice settings.

private readonly BloodColor bloodColor

The color of blood effects created when this shrapnel impacts surfaces with bloodSplashOnDeath enabled. Readonly field that determines which blood splash effect variant is spawned (Red, Green, Oil, etc).

protected bool isDead

Tracks whether the shrapnel has died and is ready for cleanup or pooling. Set to true by Death() method. Prevents redundant death calls and ensures proper cleanup sequencing before returning to object pool.

public float life

Remaining lifetime in seconds before automatic destruction. Decremented each frame and triggers Death when reaching zero. Can be reduced by collisions, environmental effects, or explicit modification.

protected Randomf random

The deterministic random number generator instance used for all randomness in the shrapnel's behavior. Initialized during Awake() with either the fixed seed or a randomized value based on RandomizeSeed flag.

public bool RandomizeSeed

When true, generates a random seed value during Awake() instead of using the fixed seed value. Randomizes the seed to a value between 0 and 999,999,999 for varied shrapnel behavior across instances.

public int seed = 10

The random seed used to initialize the Randomf instance for deterministic randomness. Default value is 10. Can be overridden by RandomizeSeed flag to use a random value, ensuring consistent behavior for replays or testing.

protected float startLife = 1f

Original lifetime value set during Launch, used for calculating fade ratios and other time-based effects. Preserved throughout the shrapnel's existence for normalized time calculations. Default is 1 second.

protected float t

Delta time value for the current frame, adjusted for time slicing. Clamped between 0 and 0.133 seconds to prevent large time jumps. When time slicing is active, this value is multiplied by the time slice amount to compensate for running fewer updates per second.