Main Elements of the Game World: Scenes and Objects

In the Scanline Engine, the game world is structured hierarchically. At the top level are Scenes, which represent distinct locations. Inside these scenes are various Scene Objects, each with specific types, roles, and properties. Here is a comprehensive overview of how scenes and their objects are constructed, managed, and utilized in the engine.

1. Scenes

A Scene is an individual 2D location in the game world, containing the player character, NPCs, and interactive or decorative elements. A scene can occupy a single physical screen or be much larger, requiring the camera to scroll and/or zoom.

Key Scene Properties:

• Depth-Scaling: Simulates a 3D perspective by scaling down objects as they move "further away" from the camera (higher up on the Y-axis). Objects can individually opt out of depth-scaling (e.g., a character climbing a vertical ladder shouldn't shrink).
• Correctional Scale: An editor-only normalization tool. Modifying this value scales the entire authored scene (including locked objects and polygons) around a shared center, preserving the relative layout of all items.
• Camera & Viewport: The scene controls the camera's X/Y coordinates and zoom level. The camera has a default zoom (applied upon loading) and a current dynamic zoom. It supports automatic centering on the player character, enabling smooth scrolling when the player approaches the edge of the screen.

2. Scene Object Hierarchy

From an Object-Oriented Programming (OOP) perspective, all elements in a scene inherit from the base SceneObject class. The class structure is organized as follows:

• SceneObject
  • PolygonObject
    • Walkbox
      • Triggerbox
  • QuadObject
  • Entity (standard Static object)
    • Actor

3. Types of Scene Objects

3.1 Static (Entity)

The Static (or standard Entity) is the foundational visual object. It is represented by a rectangle with X/Y coordinates, dimensions (width/height), a fill color, and optionally a sprite or an animation.

• Purpose: Used for backgrounds, props, and any decorative or interactive items that do not move on their own.
• Features: Sprites can be swapped dynamically at runtime via scripts.

3.2 Actor

An Actor is an extension of the Entity object.

• Purpose: Used for the player character, NPCs, and complex animated objects.
• Features: Actors possess a Direction (up, down, left, right) and a Visual State (e.g., idle, walk, talk, etc). Based on their current state and direction, they automatically play the corresponding animation set. Actors utilize A* pathfinding to navigate the scene.
• Editor Quirk: In the scene editor UI, Actor acts as a component marker. Adding the Actor component to a Static object instantly converts it into an Actor; removing it safely strips Actor-only properties (like movement speed and animation sets) and reverts it back to a Static object.

3.3 Quad (QuadObject)

A Quad is a four-vertex polygon.

• Purpose: Used to create 2.5D perspective surfaces (like floors and walls), cast dynamic shadows, and render retro-style light beams.
• Features: Every single vertex of a Quad has its own independent X, Y, and Parallax (P) coordinates, allowing it to deform correctly as the camera moves, perfectly imitating 3D perspective. Quads can also be rendered in a Retro-Grid Mode, displaying 80s-style wireframe grids alongside or instead of a fill color. Retro Grid can also act as a grid for objects to be snapped to.

3.4 Polygon Objects (Invisible Logic Zones)

These are invisible, closed polygonal areas that dictate game logic and movement.

• WalkBox: Defines the "navigation mesh" where Actors are allowed to walk. Multiple WalkBoxes interact via modes: add, subtract (cuts holes in the walkable area), and invert.
• TriggerBox: Defines an area that activates events, scripts, or story logic when an Actor overlaps with it. For instance, stepping into a TriggerBox can transition the player to a new scene, trigger an NPC dialogue, or open a subscene.

4. Common Object Properties

All SceneObject instances share a core set of properties that govern their existence in the game world:

• ID: A unique string identifier used to reference the object in scripts, the parser, or for prefab loading. Scene IDs (and object/prefab IDs) can contain backslashes (\) to denote subfolders. For example, an ID of home\room1 saves the scene as room1.json inside the home folder.
• GroupID: A unique tag starting with a # (e.g., #lights, #furniture). Objects can belong to multiple groups, allowing developers to manipulate them collectively (e.g., turning off all #lights at once).
• Disabled: A boolean flag. If true, the object is completely turned off—it is neither rendered nor able to react to any events.
• Locked: A boolean flag used purely in the editor. Locked objects cannot be selected or moved by clicking on the canvas in the editor, protecting backgrounds and large elements from accidental edits.
• Colliders (Width/Height): Present on Static and Actor objects. It defines a rectangular collision bounding box. If an object has a collider size greater than 0, it acts as a physical obstacle for moving Actors and interacts with WalkBox boundaries. Objects with a 0-size collider are "ghosts" and can be walked through.
• Parallax: Controls how fast an object moves relative to the camera.
  • 1.0 moves normally with the camera.
  • < 1.0 moves slower (used for distant backgrounds).
  • > 1.0 moves faster (used for foreground elements passing close to the screen). Parallax heavily influences both Z-sorting and 3D audio spatialization depth.
• Layer: Controls the Z-sorting (draw order) for objects that share the same parallax. Objects with a higher layer are drawn in front of those with a lower layer.
• Visual Effects: Objects natively support Opacity (0.0 to 1.0), Blend Mode (e.g., multiply, screen), and a pixel Blur filter.