SpriteSM - alexneargarder/Broforce-Docs GitHub Wiki

SpriteSM

Table of Contents

Unity Lifecycle & Setup

Methods

public override void Awake()

Unity Awake callback that initializes the sprite system. Creates normals, gets the mesh renderer component, initializes the animations array if null, builds all UV animations, and calls base initialization. This ensures all sprite components are properly set up before Start is called.

public void OnDrawGizmos()

Unity editor callback that monitors sprite changes during edit mode. Creates and maintains a SpriteMirror instance to detect property changes, automatically reinitializing the sprite when modifications are detected to ensure real-time preview updates in the editor.

protected override void Start()

Unity Start callback that plays the default animation if configured. Checks if playAnimOnStart is true, defaultAnim is within the animations array bounds, and the application is playing (not in editor mode). This allows sprites to automatically start animating when the game begins.

Sprite Management

Methods

public override void Clear()

Clears the sprite state by calling base clear functionality and stopping any current animation. If an animation is playing, it pauses the animation and sets the current animation reference to null. This effectively resets the sprite to its initial non-animated state.

public override void Copy(SpriteBase s)

Copies all settings from another SpriteSM instance. Copies base sprite properties, lower left pixel, pixel dimensions, bleed compensation, and size settings. Also duplicates the entire animations array and rebuilds all UV animations for this sprite. This creates a complete duplicate of the source sprite's visual configuration.

Parameters:

  • SpriteBase s: The source sprite to copy settings from. Must be a SpriteSM instance.

public void SetTextureDefaults()

Sets the sprite to use the full texture dimensions as defaults. Recalculates the texture reference, sets the lower left pixel to (0, texture.height), sets the sprite size to match the texture dimensions, updates pixel dimensions, calculates UVs, and updates the mesh UVs. This is useful for initializing a sprite to display an entire texture without manual configuration.

Fields

public bool lockWidthAndHeight

When true, forces the sprite's world size to exactly match its pixel dimensions. Overrides autoResize behavior and ensures 1:1 pixel-to-unit scaling regardless of other size calculation settings.

public Renderer meshRender

Cached reference to the Renderer component on this GameObject. Used for accessing the material and texture during trim operations and pixel sampling. Initialized during Awake.

private SpriteMirror mirror

SpriteMirror instance used exclusively in the editor to detect property changes. Stores a snapshot of sprite properties and compares them each frame to automatically reinitialize the sprite when modifications occur.

public bool refreshMeshNow

Editor flag that forces an immediate mesh update when set to true. Used in editor scripts to trigger sprite recreation after property changes without waiting for the next update cycle.

UV Coordinate System

Methods

public override void CalcUVs()

Calculates the UV coordinates for the sprite based on pixel coordinates. Converts the lower left pixel position to UV space and sets the UV rect's position. Then converts pixel dimensions to UV space and sets the UV rect's size. This mapping allows the sprite to display the correct portion of its texture.

public void SetLowerLeftPixel(float x, float y)

Sets the lower left pixel coordinate of the sprite on the texture and recalculates all UV mappings. Updates the UV rect position and size based on the new pixel coordinates, applies bleed compensation, and optionally recalculates the sprite size if auto-resize or pixel-perfect mode is enabled.

Parameters:

  • Vector2 lowerLeft: The pixel coordinates of the lower left corner on the texture.

public void SetLowerLeftPixel(float x, float y)

Sets the lower-left corner position of the sprite within the texture in pixel coordinates. Recalculates UV coordinates, applies bleed compensation, and optionally resizes the sprite based on autoResize or pixelPerfect settings.

Parameters:

  • Vector2 lowerLeft: The pixel coordinates of the lower-left corner in texture space.

public void SetLowerLeftPixel(float x, float y)

Sets the lower left pixel coordinate of the sprite on the texture using individual X and Y values. This is a convenience overload that creates a Vector2 and calls the main SetLowerLeftPixel method.

Parameters:

  • float x: The X pixel coordinate on the texture.
  • float y: The Y pixel coordinate on the texture.

public void SetLowerLeftPixel(float x, float y)

Sets the lower-left corner position of the sprite within the texture using individual x and y pixel coordinates. Wrapper method that creates a Vector2 and calls the main SetLowerLeftPixel method.

Parameters:

  • float x: The x pixel coordinate of the lower-left corner.
  • float y: The y pixel coordinate of the lower-left corner.

public void SetPixelDimensions(int x, int y)

Sets the pixel dimensions of the sprite on the texture and updates UV coordinates accordingly. Converts pixel space to UV space, updates the UV rect size, applies bleed compensation, and optionally recalculates sprite size for auto-resize or pixel-perfect modes. If lockWidthAndHeight is true, also updates the sprite's world size to match pixel dimensions.

Parameters:

  • Vector2 size: The width and height in pixels on the texture.

public void SetPixelDimensions(int x, int y)

Sets the pixel dimensions of the sprite region within the texture. Updates UV coordinates to match the new dimensions, applies bleed compensation, and optionally updates the sprite's world size based on lockWidthAndHeight, autoResize, or pixelPerfect settings.

Parameters:

  • Vector2 size: The width and height in pixels of the sprite region.

public void SetPixelDimensions(int x, int y)

Sets the pixel dimensions of the sprite on the texture using individual width and height values. This is a convenience overload that creates a Vector2 and calls the main SetPixelDimensions method.

Parameters:

  • int x: The width in pixels on the texture.
  • int y: The height in pixels on the texture.

public void SetPixelDimensions(int x, int y)

Sets the pixel dimensions of the sprite region within the texture using integer width and height values. Wrapper method that creates a Vector2 and calls the main SetPixelDimensions method.

Parameters:

  • int x: The width in pixels of the sprite region.
  • int y: The height in pixels of the sprite region.

Fields

public Vector2 lowerLeftPixel

The pixel coordinates of the lower-left corner of this sprite's region within the texture. Used as the starting point for UV coordinate calculations and determines which part of the texture is displayed.

public Vector2 pixelDimensions

The width and height in pixels of this sprite's region within the texture. Combined with lowerLeftPixel to define the complete rectangular area of the texture that this sprite displays.

Trim Operations

Methods

private void ExpandDown()

Expands the sprite area downward until no more non-transparent pixels are found. Checks each row below the current area, testing all pixels in that row. If any pixel has alpha greater than alphaBias, expands the area to include that row. Updates pixel dimensions, lower left position, size, and UVs to reflect the expanded area.

private void ExpandLeft()

Expands the sprite area to the left until no more non-transparent pixels are found. Checks each column to the left of the current area, testing all pixels in that column. If any pixel has alpha greater than alphaBias, expands the area to include that column. Updates pixel dimensions, lower left position, size, and UVs to reflect the expanded area.

private void ExpandRight()

Expands the sprite area to the right until no more non-transparent pixels are found. Checks each column to the right of the current area, testing all pixels in that column. If any pixel has alpha greater than alphaBias, expands the area to include that column. Updates pixel dimensions, size, and UVs to reflect the expanded area.

private void ExpandUp()

Expands the sprite area upward until no more non-transparent pixels are found. Checks each row above the current area, testing all pixels in that row. If any pixel has alpha greater than alphaBias, expands the area to include that row. Updates pixel dimensions, size, and UVs to reflect the expanded area.

public void Trim()

Automatically trims transparent pixels from all sides of the sprite to create a tight bounding box. Snaps the sprite position to 0.5 unit intervals, reduces the sprite to a 2x2 pixel area at the center, then iteratively expands outward until non-transparent pixels are found. Finally trims any remaining transparent edges. This creates the smallest possible sprite that contains all visible pixels.

private void TrimBottom()

Trims transparent pixels from the bottom of the sprite. Iterates through rows from bottom to top, checking all pixels in each row. Stops when a row contains any pixel with alpha greater than alphaBias. Updates the sprite's size, dimensions, lower left position, and UVs to exclude the trimmed area.

private void Trimleft()

Trims transparent pixels from the left side of the sprite. Iterates through columns from left to right, checking all pixels in each column. Stops when a column contains any pixel with alpha greater than alphaBias. Updates the sprite's position, dimensions, and UVs to exclude the trimmed area.

private void TrimRight()

Trims transparent pixels from the right side of the sprite. Iterates through columns from right to left, checking all pixels in each column. Stops when a column contains any pixel with alpha greater than alphaBias. Updates the sprite's dimensions and UVs to exclude the trimmed area.

private void TrimTop()

Trims transparent pixels from the top of the sprite. Iterates through rows from top to bottom, checking all pixels in each row. Stops when a row contains any pixel with alpha greater than alphaBias. Updates the sprite's size, dimensions, and UVs to exclude the trimmed area.

Fields

private float alphaBias = 0.2f

Alpha threshold value (0.2) used during trim operations. Pixels with alpha values below this threshold are considered transparent and will be trimmed. Higher values result in more aggressive trimming.

public bool trim

Editor flag that enables automatic transparent pixel trimming. When true, the sprite boundaries are automatically adjusted to exclude fully transparent edges, optimizing the sprite size.

Animation & Sprite Systems

Methods

public void AddAnimation(UVAnimation_Multi anim)

Adds a new UV animation to the sprite's animation collection. Creates a new array with one additional slot, copies all existing animations, and adds the new animation at the end. This allows dynamic addition of animations at runtime.

Parameters:

  • UVAnimation_Multi anim: The UV animation to add to the sprite.

public UVAnimation_Multi GetAnim(string name)

Retrieves an animation by name from the animations array. Searches through all configured animations and returns the first match found.

Parameters:

  • string name: The name of the animation to retrieve.

Returns:

  • UVAnimation_Multi: The UVAnimation_Multi with the specified name, or null if not found.

public UVAnimation_Multi GetCurAnim()

Returns the currently playing animation. Used to check animation state or access animation properties during playback.

Returns:

  • UVAnimation_Multi: The current UVAnimation_Multi instance, or null if no animation is playing.

public void PlayAnim(string name)

Starts playing the specified UV animation from the beginning. Resets the animation, calculates frame timing based on the animation's framerate, and begins stepping through frames. For single-frame animations, immediately triggers the completion delegate. Adds the sprite to the animated list if it has multiple frames and isn't already animating.

Parameters:

  • UVAnimation_Multi anim: The animation to play.

public void PlayAnim(string name)

Plays an animation by its index in the animations array. Validates the index is within bounds before playing the animation at that position.

Parameters:

  • int index: The zero-based index of the animation to play.

public void PlayAnim(string name)

Plays an animation by its name. Searches through all animations to find one with a matching name and plays the first match found. Does nothing if no animation with the specified name exists.

Parameters:

  • string name: The name of the animation to play.

public void PlayAnimInReverse(string name)

Starts playing the specified UV animation in reverse from the end. Resets the animation, sets it to play in reverse mode, calculates frame timing, and begins stepping backwards through frames. Handles single-frame animations and animation list management the same as forward playback.

Parameters:

  • UVAnimation_Multi anim: The animation to play in reverse.

public void PlayAnimInReverse(string name)

Plays an animation in reverse by its index in the animations array. Validates the index is within bounds before playing the animation at that position in reverse.

Parameters:

  • int index: The zero-based index of the animation to play in reverse.

public void PlayAnimInReverse(string name)

Plays the animation with the specified name in reverse direction. Searches through all animations in the animations array to find a match by name, then configures it to play backwards with the same framerate and animation settings as normal playback.

Parameters:

  • string name: The name of the animation to play in reverse.

public override bool StepAnim(float time)

Advances the current animation by the specified time and updates the sprite's UV coordinates. Calculates frames to advance based on elapsed time and frame rate. Handles animation completion according to the animation's end action (do nothing, revert to static, or play default). Triggers animation complete delegate when appropriate. Updates bleed compensation and recalculates size if in auto-resize or pixel-perfect mode.

Parameters:

  • float time: The time in seconds to advance the animation.

Returns:

  • bool: True if the animation is still playing, false if it has completed.

public override void StopAnim()

Stops the currently playing animation and reverts the sprite to its static state. Removes the sprite from the animation update list, resets the current animation's frame counter, and restores the original UV coordinates.

public void UnpauseAnim()

Resumes playback of a previously paused animation. If a current animation exists, re-adds the sprite to the animated update list to continue frame stepping.

Fields

public UVAnimation_Multi[] animations

Array of all UV animations configured for this sprite. Each animation contains frame data, timing, and playback settings. Animations are identified by name and can be played, stopped, or reversed through the animation control methods.

protected UVAnimation_Multi curAnim

The currently playing animation instance. Null when no animation is active. Used by the animation system to track frame progression, handle animation events, and determine when animations complete.

Helper & Utility

Methods

private void CheckReadbility()

Placeholder method for checking texture readability. Currently has no implementation but is called before pixel read operations. This may have been intended for runtime texture readability validation.

private Color GetPixel(float x, float y)

Gets the color of a pixel at the specified texture coordinates. Returns transparent black if the material, texture, or coordinates are invalid. Checks texture readability, validates coordinates are within texture bounds, and returns the pixel color. Note that Y coordinates are flipped since Unity textures have origin at bottom-left.

Parameters:

  • float x: The X coordinate on the texture in pixels.
  • float y: The Y coordinate on the texture in pixels (bottom-left origin).

Returns:

  • Color: The color of the pixel at the specified coordinates, or transparent black if invalid.

private float Snap(float value)

Snaps a value to the nearest interval as defined by roundInterval. Divides the value by the interval, rounds to the nearest integer, then multiplies back by the interval. This is used for pixel-perfect positioning and sizing.

Parameters:

  • float value: The value to snap to the grid.

Returns:

  • float: The value snapped to the nearest interval.

Fields

public bool round

Enables position rounding for pixel-perfect alignment. When true, sprite positions are snapped to intervals defined by roundInterval to prevent sub-pixel rendering artifacts.

public int roundInterval = 1

The rounding interval in pixels used when round is enabled. Positions are snapped to multiples of this value. Default value of 1 provides standard pixel-perfect alignment.