================================================================================
           EMPYRION BLUEPRINT READER & GENERATOR 3D (v1.0)
                         Coded by Replica
================================================================================

TABLE OF CONTENTS:
1. Overview & Capabilities
2. Reverse Engineering the Empyrion .EPB Format
3. How the 3D Generative Engines Work
   - Photo-to-Blueprint (2.5D Hull Synthesis & Multi-Layer Bases)
   - Text-to-Blueprint (Procedural 3D Sign Generator)
   - Seeded Random Color Auto-Painter
4. Standalone Executable & Packaging
5. Antivirus & Windows Defender False Positive Notice
6. Controls & Usage Reference

================================================================================
1. OVERVIEW & CAPABILITIES
================================================================================
The Empyrion Blueprint Reader & Generator 3D is a complete standalone suite 
designed for "Empyrion - Galactic Survival" (with direct integration for the 
Reforged Eden 2 scenario).

Key Features:
- Direct, high-speed binary parsing and rendering of proprietary .epb blueprints.
- Hardware-accelerated Three.js WebGL 3D viewport with unrestricted 3-axis trackball
  rotation, block inspection, and system layer toggling.
- Photo-to-Blueprint: Transforms concept art, spaceships, or architectural photos 
  into spawnable .epb files.
- Text-to-Blueprint: Procedural 3D text and sign generator with customizable font 
  scale, extrusion depth, and glowing neon/steel materials.
- Random Color Auto-Painter: Seeded coherent architectural color themes with 
  instant 3D preview and direct .epb saving.
- Scenario Explorer: Instant search and filtering of all 3,990+ scenario prefabs.
- Export to YAML & Layer-by-Layer Building Sheets for survival mode builders.

================================================================================
2. REVERSE ENGINEERING THE EMPYRION .EPB FORMAT
================================================================================
Empyrion blueprints (.epb files) are stored in an undocumented proprietary binary
container. To build this generator, the binary format was reverse-engineered 
byte-by-byte from vanilla and scenario files.

A. Container Header (16 Bytes):
   - Offset 0x00 - 0x03: Magic Identifier 0x78945245 ('ER\x94x').
   - Offset 0x04 - 0x07: Blueprint Version Integer (typically 25 for v25 formats).
   - Offset 0x08: Structure Type Byte (1 = Small Vessel / SV, 2 = Capital Vessel / CV, 
     3 = Hover Vessel / HV, 4 = Base / BA).
   - Offset 0x09 - 0x0F: Bounding Dimensions (Width X, Height Y, Depth Z) in voxels.

B. Compression & Stream Container:
   - The body of the file contains a raw Deflate stream (PK zip stream '0').
   - Unlike standard gzip or zlib streams that have 2-byte wrapper headers, 
     Empyrion uses raw Deflate blocks (RFC 1951, decoded via zlib with wbits = -15).

C. Block Dictionary & LEB128 Encoding:
   - String tables, metadata names, and device group lists are variable-length 
     prefixed using LEB128 (Little-Endian Base 128) integer encoding.
   - A block dictionary defines every unique block ID present in the structure, 
     allowing high-density index mapping.

D. 1-Bit Occupancy Bitmask:
   - To avoid storing millions of empty air voxels, Empyrion utilizes a 1-bit 
     occupancy bitmask.
   - For a vessel with dimensions W x H x D, the occupancy bitmask has length 
     ceil((W * H * D) / 8) bytes.
   - A bit value of 1 signifies a solid block exists at (x, y, z); a bit of 0 
     signifies empty space. Only coordinates with a 1 bit are stored in the voxel 
     arrays that follow.

E. 32-Bit Voxel Descriptor Stream:
   - For every occupied voxel, a 32-bit packed unsigned integer defines:
     * Bits 0..10  (11 bits): Block Type ID (0 to 2047, corresponding to game blocks).
     * Bits 11..15 (5 bits) : Block 3D Rotation Code (0 to 31).
     * Bits 16..24 (9 bits) : Variant / Damage / In-game State flags.
     * Bits 25..31 (7 bits) : Geometric Shape Variant Index (cubes, wedges, corners).

F. 30-Bit Color & Texture Packing:
   - Every block voxel carries a 30-bit color integer representing its 6 cube faces:
     * 5 bits per face * 6 faces (Top, Bottom, North, South, East, West) = 30 bits.
     * Each 5-bit value (0 to 31) indexes directly into Empyrion's standard 32-color 
       RGB palette.

G. Device Groups & Entity Metadata:
   - Functional devices (Core, Cockpits, Thrusters, Generators) are registered in a 
     device group table.
   - Coordinates are bit-packed into 32-bit integers:
     X = (packed_val >> 20) & 0xFF
     Y = (packed_val >> 12) & 0xFF
     Z = (packed_val & 0xFF)
   - Followed by LEB128-prefixed group name strings ('cpgCore', 'cpgThruster', etc.).

================================================================================
3. HOW THE 3D GENERATIVE ENGINES WORK
================================================================================

A. PHOTO-TO-BLUEPRINT (2.5D Sculpting Engine):
   - Input: Any 2D image (spaceship, concept art, vehicle, building, or castle).
   - Alpha & Silhouette Extraction: Automatically strips backgrounds and derives 
     a crisp binary mask.
   - Distance Transform & Height Mapping: Computes euclidean distance fields to 
     sculpt smooth, aerodynamic curvature and volumetric tapering along the hull.
   - Bilateral Flight Symmetry: Enforces perfect symmetry across the X-axis center line.
   - Multi-Layer Base Stabilization: For Base (BA) structures such as towers and 
     castles, the generator constructs intermediate structural reinforcement decks 
     every 6-8 vertical layers. This eliminates structural physics collapses when 
     spawning bases into Empyrion's terrain engine.
   - Hollow Cabin Generation: Generates an internal habitable space while preserving 
     an impenetrable armored outer shell.
   - Device Ingestion: Automatically embeds a functional Starter Core (Block 560), 
     cockpit canopy (Block 660), and rear thruster array.

B. TEXT-TO-BLUEPRINT (Procedural Sign Engine):
   - Input: Custom alphanumeric text (e.g. "Welcome Travelers!", "Space Station Alpha").
   - Bitmap Font Matrix: Utilizes a custom 5x7 procedural pixel font covering all 
     uppercase letters, numbers, and common punctuation.
   - Vector Extrusion: Extrudes 2D font pixels into solid 3D voxel blocks along the 
     depth axis (Z) based on user-chosen thickness (1 to 10 blocks).
   - Scale Multiplier: Scales letters from 1x (7 blocks tall) up to 4x (28 blocks tall).
   - Formatting & Kerning: Enforces automatic 1-block spacing between letters and 
     word-wraps long messages every 20-30 characters across multi-tier lines.
   - Materials: Supports glowing neon blocks (HullCombatFullLarge with emissive shaders), 
     solid combat steel, carbon plastic, and cockpit glass.

C. SEEDED RANDOM COLOR AUTO-PAINTER:
   - Generates deterministic, aesthetically cohesive color schemes using seed numbers 
     and pseudo-random number generation.
   - Architectural Themes:
     * Beskar Prime: Dark gunmetal grey, polished silver, and crimson accent stripes.
     * Stealth Operative: Deep charcoal carbon, obsidian black, and cyan accents.
     * Industrial Hazard: High-visibility yellow, hazard orange, and dark framing.
     * Faction Vanguard: Arctic white, brilliant navy/blue, and warning orange trim.
     * Crimson Fleet: Deep crimson red, black steel, and gold insignia highlights.
     * Deep Void: Navy blue, titanium grey, and electric cyan lines.
     * Rusted Scrapper: Weathered desert tan, rust-brown, and oxidized copper.
     * Arctic Frost: Pure snow white, pale icy cyan, and deep cobalt trim.
   - Real-Time Preview: Updates the WebGL instanced mesh instantly in the 3D viewport.
   - Apply & Save: Re-encodes the 30-bit color matrices and writes them directly 
     into the .epb binary file.

================================================================================
4. STANDALONE EXECUTABLE & PACKAGING
================================================================================
The application is packaged into a self-contained Windows executable:
  Release\Empyrion_Blueprint_Gen_v1.0_Replica.exe

Build Specifications:
- Compiled with PyInstaller 6.22 (Python 3.10 64-bit runtime).
- All dependencies bundled (NumPy, Pillow, PyYAML, Three.js WebGL stack).
- Embedded resources: 1,893 block database (block_palette.json), multi-res app icon,
  Three.js libraries, and CSS styling.
- Native Windows PE metadata: Version 1.0.0.0, Company "Replica", Copyright "Replica".
- Dynamic path handling: Automatically writes generated blueprints to the local 
  "output\" folder next to the .exe.

================================================================================
5. WINDOWS SMARTSCREEN NOTICE
================================================================================
When running "Empyrion_Blueprint_Gen_v1.0_Replica.exe" for the first time, Windows 
SmartScreen may display a prompt stating:
  "Windows protected your PC - Microsoft Defender SmartScreen prevented an unrecognized app from starting."

WHY THIS HAPPENS:
This is normal for newly released standalone community modding tools that do not 
carry expensive ($400+/year) commercial enterprise code-signing certificates. 
SmartScreen simply prompts for confirmation on first execution.

HOW TO RUN:
1. On the blue SmartScreen popup, click "More info".
2. Click the "Run anyway" button.
3. The application will start immediately and open the 3D desktop interface.

================================================================================
6. CONTROLS & USAGE REFERENCE
================================================================================
- Left Click + Drag  : Free 3D orbit around the model center (unconstrained 3-axis).
- Right Click + Drag : Pan the camera across the viewport.
- Mouse Wheel        : Zoom in and out.
- Mouse Hover        : Inspect block ID, category, coordinate, and color swatch.
- "Center" Button    : Re-fit and center the camera on the vessel bounding box.
- "Photo to Blueprint": Open image generator dialog.
- "Text to Blueprint" : Open 3D text/sign generator dialog.
- "Randomize Paint"  : Roll new seeded color theme.
- "Apply Paint & Save": Write chosen colors permanently into the .epb file.
- "Building Sheets"  : Generate layer-by-layer slice sheets for manual construction.

================================================================================
Created and Coded by Replica.
================================================================================
