From ed280e656b479c80555d5fb42332dae8a94fc694 Mon Sep 17 00:00:00 2001 From: Serkyo Date: Sun, 28 Jun 2026 00:51:32 +0200 Subject: [PATCH] docs(workspace): move coordinate-system rendering notes to docs/rendering.md --- AGENTS.md | 6 +----- docs/README.md | 1 + docs/rendering.md | 15 +++++++++++++++ 3 files changed, 17 insertions(+), 5 deletions(-) create mode 100644 docs/rendering.md diff --git a/AGENTS.md b/AGENTS.md index a9a028f..adb9e9e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -137,11 +137,7 @@ All registered content (blocks, items, recipes, biomes, entities, …) is identi - **Handedness:** **right-handed** (default math convention; +X right, +Y up, +Z toward the viewer / out of the screen). - **World unit:** **1 unit = 1 block.** Blocks are simply 0.5 m in physical scale, but inside the engine everything is counted in *blocks*, not metres. A player is therefore 3 units tall × 2 units wide in world coordinates. -Things to be aware of when writing rendering or import code (these are *not* convention changes — just gotchas you'll hit because the rest of the world disagrees): - -- **Vulkan clip space is Y-down** by default (and Z is `[0, 1]`, not `[-1, 1]` like OpenGL). The projection matrix has to flip Y, or you set `viewport.height` negative — both are common idioms in `ash` examples. World/view space stays Y-up; only clip space differs. -- **Blender is Z-up, right-handed.** Models exported from Blender need a coordinate swap on import (rotate −90° around X, or swap Y/Z with sign). Decide once where that swap happens — at export, at import, or never (by adopting Blender's convention) — and stick to it. Doing it in two places will eventually produce a model that's mirrored or upside-down and you'll spend an afternoon on it. -- **glTF is Y-up, right-handed** — matches your engine convention, so it's the most friction-free model format if you have a choice. +Implementation gotchas that arise because neighbouring tools use different conventions (Vulkan clip space, Blender import, glTF) are collected in [`docs/rendering.md`](docs/rendering.md). They are not convention changes — only mismatches to handle in one agreed place. ## Branching Strategy & Workflow diff --git a/docs/README.md b/docs/README.md index 660925e..d2d6352 100644 --- a/docs/README.md +++ b/docs/README.md @@ -42,5 +42,6 @@ Each subsystem note should name the design topic it implements (by title, e.g. " Subsystem notes: - [`packs.md`](packs.md) — data packs & resource packs (load order, layout, resolution). +- [`rendering.md`](rendering.md) — rendering & coordinate gotchas (Vulkan clip space, Blender/glTF import). Further subsystem notes are added here as systems are implemented and locked. diff --git a/docs/rendering.md b/docs/rendering.md new file mode 100644 index 0000000..c5c5246 --- /dev/null +++ b/docs/rendering.md @@ -0,0 +1,15 @@ +# Rendering & coordinate conventions + +Implementation notes for the `renderer` crate and for code that imports geometry. The project-wide coordinate convention itself (+Y up, right-handed, 1 unit = 1 block) is stated in [`AGENTS.md`](../AGENTS.md#coordinate-system--units); this note collects the gotchas that arise because neighbouring systems use different conventions. These are not convention changes — only mismatches to handle in one agreed place. + +## Vulkan clip space + +Vulkan clip space is **Y-down** by default, and its depth range is `[0, 1]` (not `[-1, 1]` as in OpenGL). The projection matrix must flip Y, or the viewport height is set negative — both are common idioms in `ash` examples. World and view space stay Y-up; only clip space differs. + +## Blender import + +Blender is **Z-up, right-handed**. Models exported from Blender need a coordinate swap on import: rotate −90° around X, or swap Y/Z with a sign change. Decide once where that swap happens — at export, at import, or never (by adopting the source convention) — and keep it in a single place. Performing it in two places eventually produces a model that is mirrored or upside-down. + +## glTF import + +glTF is **Y-up, right-handed**, which matches the engine convention. It is therefore the most friction-free model format when there is a choice.