# Fundamental Coding Style Rules

Codex must obey these rules without exception:

## Imports

* Each import statement must be separated by exactly **one empty line**.
* All `from` tokens must be aligned vertically using **tabs before `from`**.
* Use **double quotes** for all string literals.
* Use **ES modules** only.
* Avoid backticks unless unavoidable for syntax.

## Function Calls

* Always write calls like:
  `myFunction( param )`
  with spaces **inside** parentheses.

## Class Structure

* Exactly **one empty line** between class methods.
* No empty line at start or end of class.
* Methods must start with a blank line after `{` and end with a blank line before `}`.

## Method Body Spacing

Inside every method body:

* **One empty line between every line of code**.
* No inline comments on the same line as code.

## Callbacks & Functions

* Never write inline callbacks.
* Never write nested callbacks.
* Never pass anonymous inline functions to `.map()`, `.filter()`, `.forEach()`, etc.
* Never use arrow functions.
* Always create a separate class method instead.

## Promises

* Never use `.then()`.
* Never use `new Promise( resolve => { ... } )`.
* Always use `async` / `await`.
* Avoid `try-catch` blocks unless mandatory.

## Arrays

* Use `new Array()` instead of `[]`, **except** in Angular metadata (`imports: [ ]`, `providers: [ ]` etc.) where `[]` is allowed.

## Objects

* Never return an inline object directly.
* Always assign the object to a variable first, then return that variable.
* Align object literal values vertically using tabs before the values.

## Conditionals

* Never use short-form ternary (`? :`).
* Always write full `if` statements.

## Logging

* Do not use `$()` syntax.
* Use simple logs:
  `console.log( "message", value );`

## JSON imports

Always use:

```
import data from "./file.json" with { type: "json" };
```

## Indentation

* Use **tabs** everywhere (no spaces).
* Nested JSON or object structures must use tabs for indentation.


# Repository Guidelines

## Project Structure & Modules
- `engine/`: core rendering engine (WebGL, deferred, PBR).
- `shaders/`: GLSL shader sources; `shaders/old/` contains legacy variants.
- `plugins/`: optional features and extensions (for example `plugins/ocean`).
- `demos/`, `start.html`, `index.html`: example entrypoints for running the engine.
- `media/`: textures, models, fonts, and screenshots used by demos.
- `server.js`: minimal static HTTP server for local development.

## Build, Run, and Development
- No build step is required; files are served as static assets.
- Run `node server.js` from the repo root to start the dev server on `http://localhost:4000`.
- Open `/start.html` or files under `/demos/` in your browser to exercise changes.
- Use ES modules (`type: "module"` in `package.json`) for new JavaScript files.

## Coding Style & Naming
- JavaScript only, using ES modules and `class` syntax where appropriate.
- Use camelCase for variables and functions, PascalCase for classes and render passes.
- Match existing indentation (tabs) and brace style in the surrounding file.
- Keep core engine logic in `engine/`, shaders in `shaders/`, and optional logic in `plugins/`.

## Testing & Validation
- There is no automated test runner yet; validate behavior through demos.
- Prefer creating small, focused demo pages under `demos/` (for example `demos/rough.htm`) for new features.
- Keep demos self-contained, quick to load, and clearly named after the feature they showcase.

## Commit & Pull Request Guidelines
- Write short, descriptive commit messages (for example `Fix SSAO sampling` or `Update README images`).
- Aim for one logical change per commit when practical.
- PRs should include a concise description, a list of affected areas, and screenshots or GIFs for visual or lighting changes.
- Link to any related issues and mention relevant demo URLs (such as `/demos/new.htm`) that reviewers can open.

## Agent-Specific Notes
- When changing rendering behavior, prefer adding or adjusting render passes under `engine/renderPasses/` instead of large monolithic edits.
- Avoid deleting existing demos or media assets; add new examples alongside current ones to preserve reference behavior.