Concept: The Hinge & The Watermark

The Thesis: The Archive is "Infinite Logic." The Library is "Finite Logic."

• The Problem: The Infinite cannot fit into the Finite without breaking it. (The Superposition/Crash).
• The Goal: You are a Translator. You must find a way to "phrase" the Infinite so the Finite can understand it. This is The Hinge.

1. Visuals: "The Underdrawing" (The Watermark Overlay)

We avoid visual noise by treating the **Underdrawing (Palimpsest)** like an Ancient Architectural Draft.

• State A: Gravity (Normal Play)
• The Room looks solid, painted, and stable (Lush VGA Art).
• The Leak: Represented by Faint, Static Graphite Lines. It looks like a visible "Underdrawing" or a preparatory sketch bleeding through the paint. It is not blurring, vibrating, or noisy. It is elegant and still.
• The Threat: Knots. Only where the Underdrawing violently contradicts the Paint (e.g., a Sketch Wall cutting through a Painted Door) do you see a "Knot"—a dense, black/gold tangle where the physics engine has panicked.

• State B: Focus (Monocle Input)
• When you hold Space, the "Underdrawing" lights up and becomes solid (Sepia tones, Gold Leaf illuminations). The Painted world fades back.
• This allows you to interact with the sketch to edit its logic.

2. The Substance: Flux (Raw Potentiality)

The Archive is not empty; it is filled with Flux.

• Definition: Flux is the energy of "Indecision." It is potentiality that hasn't collapsed into a single form.
• Manifestations: It presents in four primary forms depending on what aspect of reality it destabilizes:
• Temporal Flux: Recursion, Loops, and Nonlinear causality.
• Spatial Flux: Impossible Geometry, Superposition, and Non-Euclidean spaces.
• Material Flux: Transmutation, Indecision, and Vibrating states.
• Logical Flux: Paradox, Contradiction, and Simultaneous truths.

🔍 Technical Supplement: For a deep dive into how these four types of instability actually function in-game, see The Nature of Flux.

3. The Conflict: Incorrect Integration (The Crash)

Why is the Archive dangerous? Because it contradicts the "Consensus Reality" of the Library.

• Scenario: The Archive contains the concept of [Flux] (Unceasing Change).
• The Leak: It leaks into a Statue in the Library.
• The Crash: The Statue tries to embody [Flux]. It vibrates, cracks, and tries to reshape itself every microsecond. It creates a Kinetic Hazard (Debris field).
• The "Enemy": It is the violence of incompatible definitions.

3. The Solution: The Hinge (Rewrite/Synthesis)

The End Goal is not to banish [Flux], but to Integrate it safely. You must build a Hinge—a logical adapter that connects the Impossible thought to the Real object.

• The Puzzle:
• Identify: The Monocle reveals the Knot is caused by [Flux] forcing the Stone to change.
• The Logic Gap: Stone cannot hold Flux. It is too rigid.
• The Rewrite: You identify a Metaphor that allows Stone to change without breaking. You apply the concept of [Erosion] (Time + Flux).
• The Integration (The Win):
• [Flux] + [Stone] = [Erosion].
• The vibrating, hazardous statue stabilizes. It transforms into a beautiful, weather-worn sculpture that looks like it has changed over thousands of years.
• The "Impossible" energy is now safely stored in the "Finite" form.

4. The Narrative Goal: The Great Hinge

• The Mission: You are traveling to the heart of the Archive to install The Great Hinge.
• What is it? It is the Ultimate Metaphor. Doing for the entire Archive what you did for the Statue.
• The Ending: The Archive isn't sealed away. It is Opened. But it is opened through a lens that translates its madness into "Inspiration." The Library stops being a dusty repository of dead facts and becomes a living engine of creativity.

Summary

• Visual: Elegant Graphite Sketches (Underdrawing), bleeding through the Paint.
• Conflict: Paradoxical definitions (Flux vs Stone).
• Action: Translation/Editing.
• Result: Synthesis (New Beauty), not status quo.

Core Reference: The Nature of Flux

Status: Expansion of Lore.md

Purpose: To define "Flux" not as a single mechanic, but as the fundamental state of the Archive.

1. What is Flux? (The Definition)

Flux is Raw Potentiality.

• The Consensus: In the Real World (The Library), a "Door" is a Door. It has collapsed into a single, final definition.
• The Archive: In the Archive, a "Door" is an Unfinished Thought. It is a Door, but it is also a Wall, a Window, and a Metaphor. It hasn't chosen a form yet.
• The Energy: "Flux" is the vibrating energy of things that Refuse to Settle. It is the opposite of Stasis.

2. How Flux Manifests (The Forms)

Flux is the Source, but it presents itself differently depending on what aspect of Reality it strikes. We are not shoehorned into "Transmuting Statues."

A. Temporal Flux (When Flux hits Time)

• The Manifestation: Recursion / Loops.
• The Logic: An Unfinished Thought has no "End." When it hits linear time, it breaks the concept of "After."
• The Threat: Hallways that loop forever; objects that fall and snap back; echoes of past events replaying.
• The Hinge: You must give the Loop a Conclusion (e.g., [Limit]) to stop it.

B. Spatial Flux (When Flux hits Geometry)

• The Manifestation: Impossible Geometry / Superposition.
• The Logic: An Unfinished Thought has no fixed "Dimensions."
• The Threat: Rooms that are bigger on the inside; variable gravity; "The Overbuild" (Stairs clipping through ceilings).
• The Hinge: You must give the Space a Definition (e.g., [Perspective]) to lock it down.

C. Material Flux (When Flux hits Matter)

• The Manifestation: Transmutation / Indecision.
• The Logic: An Unfinished Thought has no fixed "Material."
• The Threat: The Statue example. Solid objects vibrating, changing states (Ice -> Water -> Steam -> Gold) rapidly.
• The Hinge: You must give the Matter a Metaphor (e.g., [Erosion]) to explain the change.

D. Logical Flux (When Flux hits Meaning)

• The Manifestation: Paradox.
• The Logic: An Unfinished Thought holds contradictory truths simultaneously.
• The Threat: A Locked Door that is Wide Open. A Fire that freezes you.
• The Hinge: You must Redact one of the truths or find a Synthesis (e.g., "Cold Fire" -> [Phosphorescence]).

3. The Takeaway

Flux is exactly ONE thing: The refusal to be defined.

Flux is also EVERYTHING: Because it hasn't decided what to be yet.

This gives us the freedom to design any kind of puzzle (Time, Space, Logic, Physics) and attribute it to the same valid root cause.

← Return to Lore & Narrative

Core Reference: Game Design & Mechanics

Status: Definitive Guide (v1.1)

Philosophy: "Intellectual Archeology" - The player is a Scholar, not a Warrior. Solutions come from understanding the nature of the world, not dominating it.

1. The Core Loop

The gameplay follows a cycle of layered investigation:

1. Observe (Physical): Explore the "Painted World" to find obstacles (e.g., a crumbling bridge that disintegrates when touched).
2. Focus (Conceptual): Use the Monocle to reveal the "Underdrawing" (e.g., the bridge's structural lines are intact, but they vibrate with kinetic entropy).
3. Deduce (Inventory): Identify the Definition of your items using the Monocle.
4. Inventory Item: A Seized Clockwork Gear.
5. Definition: "It is frozen not by rust, but by a refusal to move forward. It is [Stasis]."
6. Integrate (Solution): Apply the right Concept to the Glitch.
7. Action: Use the Gear ([Stasis]) on the Crumbling Bridge.
8. Result: The Stasis transfers to the bridge, freezing its decay in a single moment, allowing the Archivist to cross the stopped debris.

2. The Monocle (The Palimpsest Lens)

The Monocle is not just an item; it is a View Mode that peels back the layer of "Paint" to reveal the original intent.

• Input: Hold [SPACEBAR].
• Effect:
• Visuals: The lush "Painted Reality" dissolves into the "Underdrawing"—a raw, sepia-toned sketch or architectural draft. erased lines and construction marks become visible.
• Movement: Disabled. The Archivist pauses to concentrate.
• Interaction: "Illuminations" (Gold Leaf details on the sketch) become interactive, representing hidden structural truths.
• Purpose: To see the Structural Intent of the world before the Flux (the raw potentiality leaking from the Archive) distorted the final image. It reveals doors that were drawn but painted over, or bridges that exist in the Underdrawing but forgot how to be solid in the final render.

3. Objects as Concepts (Hybrid Utility)

Every item interacts with the world on two distinct layers. The player controls which layer is active via the input method.

The "Lens of Use" Rule

We avoid ambiguity by strictly defining the Intent of the action based on the Monocle's state.

1. Standard Interaction (Left Click): Physical Use.
2. Context: The "Hand" cursor.
3. Logic: Literal physics.
4. Example: Use Seized Gear on Mechanism -> "It won't fit. The teeth are stripped and it refuses to turn."
5. Example: Use Empty Inkwell on Table -> "I place the glass on the table."

1. Focus Interaction (Spacebar + Left Click): Conceptual Use.
2. Context: The "Quill/Reticle" cursor (active only while holding Space).
3. Logic: Metaphorical application.
4. Example: Use Seized Gear ([Stasis]) on Crumbling Wall -> "The concept of [Stasis] halts the wall's collapse, holding the stones in suspended animation."
5. Example: Use Empty Inkwell ([Thirst]) on Obscuring Fog -> "The vacuum within the well drinks the fog, clearing the air into the glass."

The Riddle of Identification

Items are NOT explicitly labeled with their concept.

• The Riddle: Inspecting an item with the Monocle reveals its Definition—a cryptic description of its nature.
• Text: "This gear is not broken. It has simply decided that 'Now' is the only time that matters."
• The Player's Role: Deduce that this means [Stasis] (or the suspension of time) and find an instability that needs to be frozen.

4. Progression & Structure

• Metroidvania-Lite:
• The "Wings" (World Areas) are open to explore, but deeply interactive areas are gated by Conceptual Tools (e.g., You need [Perspective] to navigate the Escher-like corridors of the Infinite Wing).
• No Dead Ends:
• The Hub: Central safe zone.
• Lost & Found: Critical items left in inaccessible areas auto-migrate here.
• No Softlocks: Puzzles reset if the player leaves the room or uses the "Bookmark" (Fast Travel).

5. Interface & Interaction

Philosophy: Diegetic, Tactile, and "Quiet." The UI should feel like the Archivist's actual equipment.

The Cursor System (Context-Sensitive)

• Default State: The Golden Hand (Interact/Touch) or Boot (Walk) depending on the surface.
• Verb Cycling (Right Click): Cycles between:
• Hand: Manipulate / Take.
• Eye (Lens): Examine / Read.
• Quill: Speak / Transcribe.
• Behavior: The cursor glows or animates slightly when hovering over an interactable (Hotspot).

The Inventory (The Satchel)

• Access: Mouse swings to the Top-Right Corner (or Key [I]). The leather satchel drops down.
• Visuals: A physical grid of pockets. Items look like high-res illustrations, not icons.
• The Monocle in Inventory: You can use the Monocle inside the Satchel to inspect items for their Definition (The Riddle of Identification).

Dialogue System

• Format: Portrait-based.
• Style: No floating text boxes. Subtitles appear at the bottom in a clean serif font (Old Style).
• Topics: Keyword-based or List-based depending on context. Focusing on "Intellectual" verbs (Ask about, Theorize, Challenge).

6. Controls (Input Map)

• Left Click: Execute Action (Walk / Interact).
• Right Click: Cycle Cursor Verb.
• Double-Click: Run (2.0x Move Speed - "Monkey Island" Logic).
• Hold Spacebar: Monocle Focus Mode (Freezes Player, Reveals Underdrawing).
• Esc: Pause / Options.

Core Reference: Creative Blueprint (Implementation Strategy)

Status: Definitive Guide (v2.1)

Purpose: To define the Philosophy of Implementation. This document connects the Lore (The Nature of Flux) to the Game Design (Mechanics), serving as the rubric for puzzle and level construction.

1. Core Thesis

"Ignorance is not safety. It is merely a pause before the collapse."

• The Player Fantasy: You are not a warrior. You are a Scholar of the Impossible. Your weapon is definition; your shield is categorization.
• The Conflict: The Library's Underdrawing (Finite Structure) is being overwritten by Flux (Infinite Potential).
• The Resolution: We do not destroy the Archive; we Translate it. We effectively "edit" reality to make the impossible fit within the possible.

2. Environmental Design Philosophy

"The Shelf is a World."

We are technically "Indoors," but specfic Wings function as vast, fully realized pocket dimensions.

• Rule 1: Lush Realism (Grounded Materiality)
• The Aesthetic: High-Fidelity "Golden Age" Art (ala King's Quest VI).
• Material Truth: Environments must feel authentic to their biome. A Forest Wing features real bark, humidity, and moss. A Mountain Wing features granite and cold winds.
• The Contrast: The surrealism is achieved purely through Context (impossible locations) and Flux (structural failures), grounded against a realistic world.

• Rule 2: The Proscenium Transition
• Wings are Stages. You enter through a Frame (Archway) that dissolves into a deep horizon line, signaling the shift from "Architecture" to "Environment."

• Rule 3: Scale & Vertigo
• The Archivist is small. The World is massive. We stress the "Grand Adventure" by emphasizing verticality—towering shelves that disappear into the dark, resembling city skylines or cliff faces.

3. Puzzle Design Framework (The 4 Manifestations)

Puzzles must strictly adhere to the categories established in The_Nature_of_Flux.md. We do not create "random magic" puzzles; we create Diagnostics.

Type A: Temporal Flux (Recursion)

• The Glitch: An object lacks a "Conclusion," causing it to Loop.
• The Symptom: The Stutter. A falling book snaps back to the shelf endlessly.
• The Solve: Give it an Ending.
• Example: A "Conversation" between two stone busts is stuck in a loop because they are arguing in a circle. You must introduce a [Fact] (Inventory Item) that solves their argument. The conversation ends, and the loop breaks.

Type B: Spatial Flux (Superposition)

• The Glitch: An object lacks fixed "Dimensions," causing the Archive's geometry to clip through the Library.
• The Symptom: The Overbuild. A staircase erupts through a ceiling.
• The Solve: Re-Define the Space.
• Example: You are blocked by a "Fracture"—a shard of non-Euclidean space. You must use the Monocle to find the Architect's Anchor Point and use a [Plumb Line] to force gravity to obey local laws, snapping the room back to Euclidean alignment.

Type C: Material Flux (Indecision)

• The Glitch: An object lacks fixed "Substance," vibrating between forms.
• The Symptom: Transmutation. A stone face trying to become water.
• The Solve: Apply a Metaphor.
• Example: A wall of "Liquid Stone" flow around your tools. You apply the concept of [History] (Time). The liquid stone "remembers" it used to be solid, and calcifies instantly into a barrier.

Type D: Logical Flux (Paradox)

• The Glitch: An object holds two contradictory truths simultaneously.
• The Symptom: The Knot. A door that is both Open and Closed.
• The Solve: Redaction or Synthesis.
• Example: A "Fire" that is also "Cold" (freezing the room). You identify the contradiction. You introduce [Phosphorescence]—a concept that is "Light without Heat." The Fire accepts this new definition and becomes harmless glowing light.

4. Design Constraints (The "Don't" List)

• No "Cartoon" Logic: No "Use Rubber Chicken on Pulley." Solutions must feel like Philosophy or Physics.
• No Arbitrary Keys: We don't find "The Red Key." We find "The Concept of Permission."
• No Softlocks: The "Lost & Found" system must be robust.

Core Reference: Art Style & Visual Aesthetic

Status: Definitive Guide (v1.0)

Philosophy: "Hand-Painted VGA" (High-Fidelity Retro)

1. Visual Pillars

The visual identity of The Archive of Unfinished Thoughts is defined by the intersection of Intellectual Archeology and Impossible Geometry.

• Era Touchstone: 1992-1993 Sierra (King's Quest VI, Gabriel Knight 1).
• The Look: High-definition paintings scanned and downsampled. Texture is preferred over clean lines.
• The Feeling: Dusty, golden, ancient, weight-bearing.

What It Is NOT

• NOT "Retro" Pixel Art: No chunky visible pixels. No "8-bit" abstraction.
• NOT Vector/Flash: No smooth, flat gradients.
• NOT High Fantasy: No glowing neon magic. Metaphysics is structural (ink, stone, paper). It looks like alchemy or physics, not "spells."

2. Technical Specifications

Resolution Strategy

• Native Logic Domain: 640 x 400 (16:10 Aspect Ratio).
• Why: This provides the "sweet spot" of the VGA era—enough detail for expression, low enough to feel "crunchy" and grounded.
• Scaling:
• Art Pipeline: Created at High Res (1920x1080+) -> Downsampled to 640x400 using Bicubic Sharper.
• Display: Upscaled to modern screens (4K) using Nearest Neighbor (Integer Scaling) to preserve the sharp pixel grid.

Color Palette

• Primary: Muted Golds, Deep Teals, Oxidized Silver, Aged Parchment.
• Lighting: Warm, "Golden Hour" candlelight. Heavy use of chiaroscuro (contrast between light and shadow).
• Transparency: Magic Pink (RGB 255, 0, 255) is used for all sprite transparencies.

3. The Two Realities (The Monocle System)

Every location requires two distinct visual states.

State A: The Painted World (Standard View)

• Technique: Lush, detailed digital painting.
• Materials: Stone, Incense smoke, Stained Glass.
• Vibe: A beautiful, coherent reality.

State B: The Underdrawing (Monocle View)

• Technique: Raw Sepia / Graphite Sketch.
• Visuals: The "Paint" is stripped away. We see the architectural skeleton, the construction lines, and erased geometry.
• Signifiers: Hidden secrets appear as Gold Leaf Illuminations (flat, metallic gold).

4. Character Design ("The Scholar")

• Proportions: Realistic (6-7 heads high). Not "Chibi" or "Super Deformed."
• Pose: Upright, curious. No Combat Poses. The Archivist never holds a weapon.
• Movement: Heavy, grounded "Kinetic Weight" (Sierra-style acceleration).
• Attire: Functional scholar's robes. Satchel. Monocle (when active).

5. User Interface (Diegetic Design)

• Philosophy: The UI is physical equipment, not a HUD.
• Inventory: Use the Satchel.
• Cursors (The Golden Lens):
• Look: A simple Magnifying Glass / lens.
• Interact: A sculpted Golden Hand.
• Talk: A Quill or Speech Ribbon.
• Walk: A simple Boot.
• Style: Standalone icons (no circular frames). High contrast. Clean silhouettes on the cursor, detailed texture on the inventory.

Core Reference: World Codex (The Atlas)

Status: Definitive Guide (v1.0)

Purpose: To define the structure of the Library and the specific nature of the Flux affecting each Wing.

1. The Hub: The Grand Atrium

• Concept: The "Safe Indoors." A massive, cathedral-like central hall that connects all realities.
• Visuals: Gothic/Renaissance architecture (Marble, Brass, Stained Glass). Warm, dusty lighting (Golden Hour).
• Key Locations:
• The Archivist's Desk: Central save/crafting point.
• The Lost & Found: Where lost items respawn.
• The Great Seal: The massive, cracked door leading to The Archive (Wing 5).
• Flux State: Stable. This is the Anchor. Physics works normally here, though tremors (Screen Shake) occasionally remind you of the instability below.

2. Wing 1: The Atlas of Impossible Geography (The Patchwork)

• Theme: The Glitch Quilt (Biomes w/ Hard Borders).
• The Environment: Hyper-Real "Map Tiles." It is not paper, but a lush, vibrating reality where the "Map" was assembled wrong.
• The Look: Lush Romanticism. Thick, humid Rainforests (Vines, Waterfall mist, glowing flora) that end in a razor-sharp, straight line.
• The Transition: One step past the Jungle "Seam" is a frozen, diamond-dust Tundra. The transition is instantaneous.
• The Flux: Spatial Flux (The Seam).
• Manifestation: Weather systems collide at the borders. Rain turns to ice mid-air. Trees are sliced in half by the biome shift.
• The Knots: The Cliffs of Logic. A river flowing out of a Jungle and vanishing into a Desert void.
• The Hinge Concept: [Context]. You must find the logic that connects the mismatched tiles (e.g., rerouting the river to "stitch" the Jungle to the Desert).
• Key Location: The Precipice (Scene 01). The "Edge" of the Hub's reality. You stand on a high cliff looking out over the chaotic patchwork of mismatched biomes stretching to the horizon. The world is contiguous, but the transitions are violent cuts.

3. Wing 2: The Encyclopedia of Extinct Sounds (The Canyon)

• Theme: The Whispering Canyon (Erosion & Echoes).
• The Environment: Eroded Sandstone Giants. Towering red cliffs carved by wind into natural flutes and organ pipes. Hanging gardens and waterfalls add lushness.
• The Flux: Temporal Flux (The Echo).
• Manifestation: Sound precedes cause. You hear a rockfall before it happens.
• The Knots: Sound Barriers. Solid walls of noise that block physical passage.
• The Hinge Concept: [Resonance]. You must find the resonant frequency (Wind/Tune) that harmonizes with the stone to open the path.

4. Wing 3: The Biography of the Unborn

• Theme: Identity & Potential.
• The Environment: A Sea of Mist dotted with white marble islands (giant, half-carved statues of people).
• The Flux: Identity Flux (Material Indecision).
• Manifestation: The statues change faces. A "Warrior" statue flickers into a "Poet" because it wasn't finished.
• The Knots: "Concept Storms"—clouds of unformed traits that strip your inventory of its definitions.
• The Hinge Concept: [Definition]. You must decide who the statue is (Inventory: Give the Warrior a Sword) to lock it into reality.

5. Wing 4: The Mathematics of the Infinite

• Theme: Recursion & Logic.
• The Environment: An Escher Labyrinth. Staircases that go up and down forever. Fractals.
• The Flux: Recursive Flux (Paradox).
• Manifestation: Rooms that contain themselves. Doors that open into the wall behind you.
• The Knots: "Logic Loops." Infinite corridors that trap you until you solve the equation.
• The Hinge Concept: [Limit]. You must introduce a "Stop" command to the infinity to make it calculable.

6. Wing 5: The Archive Itself (The Source)

• Theme: The Raw Draft.
• The Environment: The Sediment. It looks like the "Backstage" of the universe. Piles of discarded concepts, raw geometry, and floating text.
• The Flux: The Source. Here, Flux is the air itself.
• The Goal: Install The Great Hinge. Translate this chaos into the Library's new Inspiration Engine.

Core Reference: Technical Specifications

Status: Definitive Guide (v1.0)

Purpose: To define the Engine Constraints and Rendering Pipeline required to support the Creative Vision (Hand-Painted VGA + Monocle Mechanics).

1. Engine Architecture

• Language: C (C99 Standard).
• Library: Allegro 4.2 (Static Link).
• Rationale: Provides authentic software rendering limits, verifying inherent "retro" feel without artificial filters. Allows for DOS cross-compilation.
• Target Platforms:
• Primary: Linux (Development/Release).
• Secondary: Windows 98/XP/10 (Release).
• Legacy: MS-DOS 6.22 (CWSDPMI).

2. Display & Resolution Strategy

• Logical Resolution: 640 x 400 (16:10 Aspect Ratio).
• Color Depth: 32-bit (Internal) -> Dithered/Downsampled options for Legacy Targets.
• Scaling Logic:
• Modern Screens: Integer Scaling (Nearest Neighbor) with Pillarboxing.
• Legacy Screens: Native VGA Mode 13h / Mode X equivalents where supported.

3. The Rendering Pipeline (Monocle System)

The "Monocle" (Underdrawing) requires a custom multi-plane renderer.

Layer Stack (Bottom to Top)

1. Background Plane A (The Paint): Standard VGA Background (BMP/PCX).
2. Background Plane B (The Underdrawing): Sepia/Lineart version of the room.
3. Behavior: By default, Plane A is 100% Opaque. Holding [SPACEBAR] Cross-fades or Cuts to Plane B.
4. Flux Overlay (The Watermark):
5. Asset: Transparent Sprite Overlay (Graphite Lines/Geometry).
6. Blend Mode: Additive or Alpha-Blended.
7. Behavior: Visible in Both states, but glowing in State B.
8. Object/Actor Layer:
9. Sorted by Y-Coordinate (Z-Buffer simulation).
10. Sprites must have valid "Walk-Behind" masks (Depth Map).
11. UI Layer: Standard Cursor/Text rendering.

4. Input State Machine

The Engine must support two distinct Input Modes mandated by Game Design.md:

• Mode 1: Physical (Standard)
• Cursor: Hand/Boot.
• Click: Pathfinding (A* or Polygon Nav).
• Mode 2: Conceptual (Focus)
• Trigger: Hold [SPACEBAR].
• State Change: Player Movement DISABLED.
• Cursor: Quill/Reticle.
• Click: Interaction with "Illuminations" (Hotspots on Plane B).

5. File Formats & Assets

• Images: BMP (24-bit) or PCX (8-bit palletized) for background compatibility.
• Sprites: TGA/PNG (Source) -> Converted to Allegro-friendly bitmaps at element time.
• Audio: WAV (Sound Effects), OGG (Music - Modern), MOD/MIDI (Music - Legacy).
• Scripts: Custom Bytecode or Plain Text parsing for Room Logic (Hotspots, Exits).

6. Performance Budget

• Target Framerate: 60 FPS (capped).
• Memory Footprint: < 64 MB (Ideally < 16 MB for DOS compatibility modes).

Core Reference: Project File Structure & Architecture

Status: Authoritative Guide (v1.0)

Purpose: To define the Strict Hierarchy of the project. All assets, logic, and documentation must adhere to this structure to ensure the game remains manageable as it scales to hundreds of scenes.

1. Top-Level Hierarchy

The project root (/The Archive of Unfinished Thoughts/) is divided into three domains:

• Codex/: Creative Documentation & Design Specs.
• c_allegro/: Source Code, Build Scripts, and Compiled Binaries.
• c_allegro/assets/: Runtime Game Assets (Art, Audio, Data).

2. Documentation Structure (`Codex/`)

Organized by Scope (Global vs. Local).

• Core Reference/ (Global Truths)
  • Art Style.md
  • Creative_Blueprint.md (Implementation Philosophy)
  • File_Structure.md (This Document)
  • Game Design.md
  • Lore.md
  • Technical_Specifications.md
  • The_Nature_of_Flux.md
  • World Codex.md (Atlas of the Hub & Wings)
• Area Specific/ (Local Truths)
  • Hub/
    • Grand_Atrium/
  • Wing/
    • wing_01/
      • Characters.md (The Wing's Cast)
      • scene_01_precipice/
        • concept.md (Narrative intent)
        • script.md (Puzzle logic & dialogue)
        • assets.md (Asset checklist)

3. Asset Architecture (`c_allegro/assets/`)

Organized by Context. Assets are grouped by where they are loaded.

A. Global Assets (`assets/global/`)

Things that are Always Loaded or shared across multiple wings.

• ui/: Cursors, Menus, Inventory UI, Font Maps, Monocle Overlays.
• characters/
  • archivist/ (The Player Character)
    • anim_walk_down.bmp
    • _build_files/ (Source PSDs/Aseprite - Ignored by Git)
  • mentor/ (Global NPC)
    • anim_idle.bmp
    • _build_files/
• audio/
  • sfx/: Physical UI sounds (Satchel open, Footsteps).
  • music/: OGG/MIDI tracks (e.g., mus_theme_main.ogg).
  • speech/: Voice lines organized by Scene ID (e.g., vox_01_01_archivist_look_door.ogg).
• text/:
  • strings.dat (Global UI labels, Menu text).
  • dialogue_global.dat (Generic responses like " I can't do that").
• items/:
  • ico_lantern.bmp (Inventory Illustration)
  • _build_files/

B. Scene & Wing Assets (`assets/wings/`)

Organized nicely into Wing -> Scene containers.

• wing_01/ (The Atlas)
  • audio/ (Wing-Specific Music/Ambience)
  • characters/ (Wing-Specific NPCs)
    • cartographer/
  • objects/ (Wing-Wide Objects)
  • text/ (Wing-Wide Dialogue/Strings)
  • scenes/
    • scene_01_precipice/
      • audio/ (Scene-Specific SFX/Ambience)
      • text/ (Runtime Script Data)
        • dialogue.dat
      • layers/ (The Visuals)
        • bg_paint.bmp (Layer A: Painted World)
        • bg_sketch.bmp (Layer B: Underdrawing)
        • fg_overlay.bmp (Foreground Parallax - Optional)
        • flux_overlay.bmp (The Watermark)
      • masks/ ( The Nav Data)
        • mask_walk.bmp (Navigation Mesh)
        • mask_depth.bmp (Z-Buffer / Scale Map)
      • objects/ (Scene-Bound Interactables & Entities)
        • obj_bridge_crumbling.bmp
        • obj_bridge_fixed.bmp

4. Code Architecture (`c_allegro/src/`)

Separated into Engine (The Machine) and Game (The Content).

A. The Core Engine (`src/engine/`)

Generic systems that don't know about "The Archive."

• display.c: Windowing, Scaling, Pillarboxing.
• input.c: Mouse bridging, Keyboard state.
• graphics.c: Bitmap loading, Blitting, Transparency.
• audio.c: Sound mixing.
• scene.c: The abstract concept of a "Scene" (loading data).
• actor.c: Sprite animation and movement.

B. The Game Logic (`src/game/`)

Specific logic for This Game.

• main.c: The Entry Point.
• scene_registry.c: The database of all Scenes (maps IDs to file paths).
• inventory.c: Logic for the Satchel and Items.
• puzzles.c: Global flags and puzzle state management.
• scripting.c: The parser for Scene Events.

C. Headers (`c_allegro/include/`)

Mirrors the src/ structure.

• include/engine/*.h
• include/game/*.h

5. Build System

• Makefile: The master build script.
• obj/: Intermediate object files (ignored by git).
• bin/: Final Executables.
  • archive.x86_64 (Linux)
  • archive.exe (Windows)

6. Naming Conventions

• Files: lowercase_with_underscores (e.g., bg_paint.bmp).
• Scenes: wing_xx_name (e.g., wing_01_atlas).
• Code: lowercase_with_underscores for C files.
• Defines: UPPERCASE_WITH_UNDERSCORES (e.g., SCREEN_WIDTH).