islaApocalypse/Core/Scripts/README.md

📜 Core Scripts Directory - Isla Apocalypse

Overview

The /Core/Scripts directory is the dedicated code repository for all pure C# data structures, universal enumerations, and static mathematical utilities. Everything in this folder is compiled into the shared assembly used by both the authoritative /Server and the rendering /Client.

Core Philosophy: "Pure Data, Zero State." Scripts in this folder define what things are and how to calculate them, but they never remember current game events. They do not track who is online, what chunks are loaded, or what time of day it is. They are stateless, universal blueprints.

---

🧩 Current Systems (Phase 2)

1. The Voxel Palette System

• BlockData.cs: The fundamental struct defining the properties of a single voxel (ID, Name, IsSolid, BaseColor).
• BlockRegistry.cs: The static master dictionary. Contains the hardcoded IDs for every block in the game (Air, Bedrock, Dirt, Asphalt) and provides a safe lookup method (GetBlock) for both the mesher and the physics engine.
• BiomePalette.cs: The translation layer between 2D and 3D. Contains the logic that dictates the vertical stacking of blocks based on biome and depth (e.g., ensuring mountains have stone beneath snow, and roads are topped with asphalt).

2. Universal Identifiers

• Enums.cs: The master repository for global enums (Biome, TownTier, MapHalf). By keeping these here, the offline Map Generator, the Server, and the Client are guaranteed to use the exact same integer values for biomes and POIs.

---

🚀 Future Roadmap & Planned Additions (Phase 2 & 3)

As we build the 3D Chunk Manager and multiplayer networking, this folder will expand to include:

3. The Blueprint Parser

• MapDataParser.cs (Next Step): A static utility to open and decode the MapData_Seed_[X].dat binary file into usable C# arrays for the Server to ingest.

4. Chunk Data Structures

• ChunkData.cs: The raw 3D array (byte[,,]) that holds the voxel IDs for a specific 16x16x64 area.
• Note: This structure will include the IsPlayerProtected boolean flag to support the "Land Claim" delta-backup system, preventing player bases from being wiped out by chunk corruption.

5. Math & Coordinate Utilities

• VoxelMath.cs: Static helper functions for translating massive 3D World Coordinates into local Chunk Coordinates (e.g., finding out which specific chunk file to load when a player walks to X: 5000, Z: -200).

6. Network Packet Definitions

• Structs that define the exact byte layout of multiplayer messages (e.g., PlayerDigPacket, ChatPacket) to ensure precise Server/Client synchronization.

---

⚠️ Directory Rules & Best Practices

1. No Godot Node Inheritance: Scripts here should rarely, if ever, inherit from Node or Node3D. They are pure C# classes, structs, or static utilities.
2. No _Process or _Ready: Because these are not attached to active objects in the game world, they do not use Godot's frame-by-frame loop functions.
3. Strictly Independent: A script in /Core/Scripts cannot reference anything in /Client or /Server. The dependency flows one way: the Client and Server look in to the Core; the Core never looks out.