Kepler/AGENTS.md

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.