beezm/islaApocalypse
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: bring all READMEs current with actual code (post-sweep-10 truth pass)

Browse source 
Every README was read first, checked against the code in its directory, then
rewritten to describe what the code actually does now.

Corrected throughout: map size is config-driven (8192 default) not a fixed
4096; chunks are 24x24x256 not 32x32; road carving is implemented for all four
tiers, not a 'next step'; Data/ and Resources/ are empty, not populated.

Also fixed MATH_MARCHING_CUBES.md, which documented the density sign convention
exactly backwards — it claimed positive was underground, where the code treats
positive as above the surface and counts a corner inside when density < iso.
Getting that backwards inverts every normal, a bug this project has hit before.

The root README now carries accurate run steps: F5 runs the map generator (not
the game), F6 on Scenes/Main.tscn runs the 3D world, and ChunkRadius is a load
radius that should be dropped to 4-8 while iterating.

Docs only. No code changed.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Stewart Howe 2026-08-05 05:23:58 -04:00
parent f9ea2da3f4
commit d72ffc0183
13 changed files with 579 additions and 409 deletions
Download patch file Download diff file Expand all files Collapse all files

73
Resources/README.md
View file

@ -1,49 +1,24 @@
# 📦 Resources Directory - Isla Apocalypse
## Overview
The `/Resources` directory acts as the game's central library for all static assets and Godot-specific data containers (primarily `.tres` files, 3D models, textures, and audio).
**Core Philosophy: "The Reusable Building Blocks."**
If the Server is the brain and the Client is the eyes, Resources are the memories. They define the *properties* of things in the world. If there are 50 zombies on screen, you don't want 50 copies of their texture and max health data in your RAM. Instead, all 50 zombies reference a single `ZombieBase.tres` resource.
---
## 🧩 Core Systems (Phase 2 & 3)
### 1. Voxel & Block Definitions
* **Format:** Custom `.tres` files based on a `BlockData` C# script (located in `/Core`).
* **Function:** Defines the properties of every voxel in the game.
* **Examples:** `Dirt.tres` (Texture: brown_dirt.png, Durability: 100, StepSound: dirt_crunch.ogg), `Asphalt.tres` (Texture: road.png, Durability: 500, StepSound: hard_step.ogg). Both the Client and Server read these to know how a block looks and behaves.
### 2. Item & Inventory Data
* **Format:** Custom `.tres` files for `ItemData`.
* **Function:** Defines every item a player can hold, craft, or drop.
* **Examples:** `StoneAxe.tres` (Icon: axe.png, Damage: 15, BlockDamage: 40, MaxStack: 1). The Server uses this to calculate damage; the Client uses this to draw the icon in your hotbar.
### 3. Audio & Visual Assets
* **Materials & Shaders:** The `.material` and `.gdshader` files used by the Client's chunk mesher (e.g., `TerrainMaterial.tres`).
* **3D Models:** The `.glb` or `.gltf` files for weapons, dropped items, and entities.
* **Audio Streams:** The `.wav` or `.ogg` files for ambient wind, UI clicks, and zombie attacks.
### 4. UI Themes & Fonts
* Godot `Theme` resources that dictate the colors, fonts, and border styles of the entire user interface, ensuring the inventory menus match the main menu.
---
## 🚀 Directory Organization Strategy
To prevent this folder from turning into a massive junk drawer, it must be strictly subdivided:
* `/Resources/Blocks/`
* `/Resources/Items/`
* `/Resources/Models/`
* `/Resources/Audio/`
* `/Resources/UI/`
---
## ⚠️ Directory Rules & Best Practices
1. **Text Over Binary:** Always save custom Godot resources as `.tres` (Text Resource) rather than `.res` (Binary Resource). Text resources can be read by version control (Git), allowing you to see exactly when someone changed the damage of a Stone Axe from 15 to 20.
2. **Stateless Data Only:** A Resource should never track live game state. For example, `Pistol.tres` holds the *Max Ammo* capacity (15), but it should NEVER hold the *Current Ammo* (7). Current ammo is a live state tracked by the Server.
3. **Shared Access:** Because Resources are just data, they are completely safe to be referenced by both the `/Server` and the `/Client`.
# /Resources
Intended home for Godot `.tres` asset definitions and static assets — block properties, item data,
materials, models, audio, UI themes.
## ⚠️ Currently empty
**This directory holds nothing but this README.** No resources exist yet.
Block properties currently live **in code**, not in resources: `Core/Scripts/BlockRegistry.cs` builds
its dictionary of `BlockData` (ID, name, IsSolid, colour) in a static constructor. Terrain rendering
uses a `StandardMaterial3D` created at runtime per chunk in `ChunkRenderer.cs`, not a saved material.
Moving that data into `.tres` files is a reasonable future step — it would make block definitions
editable without recompiling and diffable in git — but nothing depends on it today.
## Conventions, if and when it fills up
1. **`.tres`, not `.res`.** Text resources are readable in a diff; binary ones are not.
2. **Stateless only.** A resource holds a weapon's *max* ammo, never its *current* ammo. Live state
belongs to the server.
3. **Subdivide early** — `Blocks/`, `Items/`, `Models/`, `Audio/`, `UI/` — before it becomes a junk
drawer.
4. Resources are plain data, so both `/Server` and `/Client` can safely reference them.