Core Concepts & Architecture

Read time 4 minutes

---

Understanding the fundamental architecture of Luna Tools and Marvel’s Spider-Man 2 asset structures is essential for successful, bug-free modding. This guide explains the core mental models behind Stages, asset addressing, streaming zones, actors, visual scriptgraphs, and sidecar metadata.

---

1. The Stage System: Non-Destructive Modding

In traditional modding tools, making an edit often means directly overwriting game archive files, which is a risky practice that can corrupt game installations and make tracking changes difficult.

Luna Tools uses a Stage-based Virtual Overlay System:

flowchart TD
    subgraph VanillaGame["Marvel's Spider-Man 2 Archives"]
        TOC["Game TOC (Master Index)"]
        VanillaZone["zone_times_square.zone (Archive 04)"]
        VanillaModel["spiderman_hero.model (Archive 12)"]
    end

    subgraph UserStage["Your Active Stage (e.g., D:/MyMod)"]
        StageZone["levels/manhattan/zone_times_square.zone"]
        StageTexture["textures/characters/suit_diffuse.texture"]
    end

    subgraph RuntimeEngine["Luna Tools Runtime Resolution"]
        Resolver{"Asset Resolver"}
        Output["Composed Viewport / Game Output"]
    end

    VanillaZone -.->|Fallback if not in Stage| Resolver
    VanillaModel -.->|Direct Read| Resolver
    StageZone -->|Stage Override Priority| Resolver
    StageTexture -->|Stage Override Priority| Resolver
    Resolver --> Output

Key Principles of Stages

1. Overlay Hierarchy: When an asset is requested, Luna Tools first checks if a file exists at the matching logical path inside your active Stage folder. If found, the Stage file takes precedence; otherwise, the original file is loaded seamlessly from the game's TOC archives.
2. Path Mirroring: Files in a Stage mirror their exact logical game paths. For example:
   • Logical Game Path: levels/manhattan/zones/zone_central_park.zone
   • Stage Disk Path: D:\Projects\MyMod\levels\manhattan\zones\zone_central_park.zone
3. Pristine Game Archives: The game TOC and base installation are treated as strictly read-only. Luna Tools never overwrites vanilla archive archives (.toc or .archive chunks).
4. Mod Exporting: When you select Stage → Export Mod (.stage) (Ctrl+E), Luna Tools packages your Stage into a single, clean .stage archive ready for mod managers or game distribution.

---

2. Asset Identity & Logical Addressing

Inside the game engine, assets are not referenced by Windows filesystem paths like C:\Games\Asset.bin. Instead, every asset is identified through two synchronized representations:

1. 64-Bit Asset Hashes (Asset IDs)

At the lowest engine level, every asset is identified by a 64-bit unsigned integer hash (e.g., 0x8f4c1e92a0b3d671). When the game engine calls LoadAsset(), it passes this 64-bit ID.

2. Logical Relative Paths

Human developers and designers reference assets by their normalized logical relative paths, such as:

• actors/hero/hero_spiderman_symbiote.actor
• cinematics/missions/intro/intro_rooftop_confrontation.ltcinematic
• materials/surfaces/concrete_wet_pavement.ltsurface

Why Hashlists Matter

A name list can help the Asset Browser display readable paths instead of numeric IDs.

---

3. Zones, Levels & World Streaming

Marvel's Spider-Man 2 features an expansive, seamless open-world streaming engine. The world is structured into a hierarchical streaming tree:

graph TD
    World["New York City World"]
    LevelManhattan["Manhattan.level"]
    LevelQueens["Queens.level"]
    LevelBrooklyn["Brooklyn.level"]

    World --> LevelManhattan
    World --> LevelQueens
    World --> LevelBrooklyn

    RegionMidtown["Region: Midtown Manhattan"]
    RegionFinancial["Region: Financial District"]

    LevelManhattan --> RegionMidtown
    LevelManhattan --> RegionFinancial

    ZoneTS["zone_times_square.zone"]
    ZoneEmpire["zone_empire_state.zone"]

    RegionMidtown --> ZoneTS
    RegionMidtown --> ZoneEmpire

• Levels (.level): Broad world partitions grouping regions and setting up global environment bounds, loading conditions, and world-space origins.
• Regions: Logical bounding volumes used by the streaming manager to trigger memory allocation and asynchronous asset prefetching.
• Zones (.zone): The atomic streaming units of the game world. A .zone file contains:
  • Placed scene actors (pedestrians, vehicles, interactive props, lights, audio emitters).
  • Static geometry and placement transforms.
  • Havok collision shapes and navigation data.
  • Embedded or linked Scriptgraphs controlling zone-specific missions, encounters, and triggers.

---

4. Actors: Blueprint vs. Instance vs. Spawn Template

When working in the Actor and Zone editors, keep these three distinctions clear:

Actor Concept	Format / Representation	What It Does
Actor Definition	.actor file	The master blueprint defining components, skeleton bindings, material profiles, hitboxes, and physics behaviors.
Placed Scene Instance	Zone table entry	A specific, persistent actor placed directly in a .zone file with fixed world-space transform coordinates $(X, Y, Z, \text{Yaw}, \text{Pitch}, \text{Roll})$ and unique instance ID.
Spawn Template	Reference handle in script	A blueprint reference passed to a visual scripting node (e.g. SpawnActorAtMarker) to dynamically generate runtime enemies or vehicles during gameplay.

IMPORTANT

Runtime Actor Handles: An actor variable in a scriptgraph is merely an empty storage slot for an ActorHandle. It does not create or spawn a character by itself until a spawn action or query assigns a valid runtime handle to it!

---

5. Visual Scripting & Scriptgraphs

Gameplay mechanics, interactive encounters, mission objectives, and cinematic cues are authored visually using Scriptgraphs.

A Scriptgraph contains two fundamentally distinct types of node connections:

flowchart LR
    subgraph Flow["Signal Flow (White / Thick)"]
        Trigger["OnPlayerEnterTrigger"] -->|Signal Pulse| Spawn["SpawnEnemyGroup"]
        Spawn -->|Signal Pulse| Play["PlayCombatMusic"]
    end

    subgraph Data["Variable Flow (Colored / Thin)"]
        TargetMarker["SpawnMarkerTransform"] -->|Transform Data| Spawn
        VolumeLevel["MusicVolume (Float 0.8)"] -->|Float Data| Play
    end

Signals (Control Flow)

• Represent the execution timeline.
• Fired by triggers, timers, or completion events.
• Indicated by triangular connection pins and bold lines.
• Control when actions execute.

Variables (Data Flow)

• Carry typed information into action parameters.
• Indicated by circular colored pins and thin lines.
• Types include: Boolean, Integer, Float, Vector3, Transform, String, ActorHandle, and EventPayload.
• Control what data actions operate on.

Subgraphs

Complex mission sequences can be organized into modular Subgraphs. Subgraphs act like reusable subroutines, accepting input signals and parameters and exposing output execution pulses without cluttering the master graph canvas.

---

6. Asset files and editor information

Some assets have a companion file that stores editor information, such as graph layout. Keep companion files together with their assets when moving or sharing a project.

7. Checking your work

Save and reopen edited assets to check your changes. Preview where possible, then test the finished stage in game; a successful save alone does not confirm gameplay behavior.