From 81ed1d92010fb996ac7e39825cd1a2f4f6452f9d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=9C=D0=B8=D1=85=D0=B0=D0=B8=D0=BB=20=D0=9A=D0=B0=D0=BF?= =?UTF-8?q?=D0=B5=D0=BB=D1=8C=D0=BA=D0=BE?= Date: Tue, 20 Oct 2026 07:01:30 +0300 Subject: [PATCH] some --- AGENTS.md | 114 +++++++++++++++++++++++++++++-------- game/ver-mac/Package.swift | 2 +- 2 files changed, 92 insertions(+), 24 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2923098..89c46ba 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,9 +12,9 @@ and talk to the engine through generated functions like `rootSet(...)`. Remote: `https://git.opengamestudio.org/mahjong/mahjong` · Version: `2.0.0` -> Current `dialect.yml` is still the "Root / counter" template inherited from the -> dialect example — the Mahjong game logic has not been written yet. The app -> shell, packaging and symlink wiring are in place. +> `dialect.yml` is still the "Root / counter" template with a `Render` context +> bolted on: the Mahjong game logic has not been written yet. The app shell, +> packaging, symlink wiring and the raylib renderer are in place. ## Structure @@ -28,28 +28,47 @@ components/ SHARED source-of-truth for all components. root/root.swift RootComponent (owns DialectController, registers effects + shoulds, sets didSetup on setup()) root/rootVM.swift RootVM (ObservableObject / @Published countText) - root/mac/view/RootView.swift Per-platform SwiftUI view + root/mac/view/RootView.swift SwiftUI view: RenderView in a ZStack + UI + render/render.swift RenderComponent (controller, effects + shoulds) + render/renderVM.swift RenderVM (weak shared; glView, didPrepareGL, + pixelSize, startTime, timer) + render/renderConst.swift RENDER_CONFIG (sr_config), RENDER_FPS, + RENDER_MODEL_CUBE, RENDER_OPENGL_ATTRS + render/renderConstShader.swift RENDER_SHADER_* GLSL sources (GLSL 150) + render/renderAux.swift renderDraw(vm), renderPixelSize(view) + render/renderEffect.swift renderInit, renderLoadCubeModel, + renderStartTimer, renderDeinit + render/mac/view/RenderGLView.swift Thin NSOpenGLView: pixel format, callbacks + -> renderSet(...), draw -> renderDraw + render/mac/view/RenderView.swift NSViewRepresentable wrapper game/ver-mac/ macOS app (SPM executable target "ogs-mahjong") - Package.swift SPM manifest (macOS 13+, swift-tools 5.9); SPM C target - "RaylibBridge" (bridge/) + links Homebrew raylib + Package.swift SPM manifest (macOS 13+, swift-tools 5.9); C target + "RaylibBridge" (bridge/) + links Homebrew raylib; the + Swift target gets -Xcc -DGL_SILENCE_DEPRECATION Info.plist Bundle id org.opengamestudio.Mahjong, exec ogs-mahjong Resources/AppIcon.icns App icon Resources/assets/ Bundled glTF assets: cube.gltf (static), - cube_texture.png - bridge/ C target "RaylibBridge": raylib_bridge.{c,h}. Renders a - rlgl scene (no raylib window) into an NSOpenGLView. + cube_texture.png, cube_normal.png + bridge/ C target "RaylibBridge": raylib_bridge.{c,h} with the + public header in include/. Renders an rlgl scene (no + raylib window) into the NSOpenGLView. src/ GameApp.swift @main SwiftUI App entry - AppDelegate.swift Creates RootComponent + RootVM, calls root.setup() + AppDelegate.swift Creates Render/Root components + VMs, calls setup() dialect.swift GENERATED — do not hand-edit (see chicken-egg below) - other/other.swift -> symlink components/other/other.swift - render/renderConstShader.swift -> symlink components/render/renderConstShader.swift - render/view/RenderGLView.swift -> symlink components/render/mac/view/RenderGLView.swift - render/view/RenderView.swift -> symlink components/render/mac/view/RenderView.swift - root/root.swift -> symlink components/root/root.swift - root/rootVM.swift -> symlink components/root/rootVM.swift - root/view/RootView.swift-> symlink components/root/mac/view/RootView.swift + other/other.swift -> symlink components/other/other.swift + render/render.swift -> symlink components/render/render.swift + render/renderAux.swift -> symlink components/render/renderAux.swift + render/renderConst.swift -> symlink components/render/renderConst.swift + render/renderConstShader.swift -> symlink .../renderConstShader.swift + render/renderEffect.swift -> symlink components/render/renderEffect.swift + render/renderVM.swift -> symlink components/render/renderVM.swift + render/view/RenderGLView.swift -> symlink components/render/mac/view/... + render/view/RenderView.swift -> symlink components/render/mac/view/... + root/root.swift -> symlink components/root/root.swift + root/rootVM.swift -> symlink components/root/rootVM.swift + root/view/RootView.swift -> symlink components/root/mac/view/... ref/swiftraylib Symlink to ../../swiftraylib — the raylib/SwiftUI renderer sample the game will use for 3D rendering. @@ -73,7 +92,12 @@ directories whose files are **relative symlinks** back into `components/`: ``` src/other/other.swift -> ../../../../components/other/other.swift (4 up) +src/render/render.swift -> ../../../../components/render/render.swift (4 up) +src/render/renderAux.swift -> ../../../../components/render/renderAux.swift (4 up) +src/render/renderConst.swift-> ../../../../components/render/renderConst.swift (4 up) src/render/renderConstShader.swift -> ../../../../components/render/renderConstShader.swift (4 up) +src/render/renderEffect.swift -> ../../../../components/render/renderEffect.swift (4 up) +src/render/renderVM.swift -> ../../../../components/render/renderVM.swift (4 up) src/root/root.swift -> ../../../../components/root/root.swift (4 up) src/root/rootVM.swift -> ../../../../components/root/rootVM.swift (4 up) src/root/view/RootView.swift-> ../../../../../components/root/mac/view/RootView.swift (5 up) @@ -114,11 +138,48 @@ The 3D scene links against Homebrew **raylib** (`brew install raylib`). The The bridge renders with raylib's rlgl layer into an `NSOpenGLView` — raylib never creates its own window. `RootView` puts `RenderView` (backed by `RenderGLView`) behind the SwiftUI UI in a `ZStack`. A textured cube is drawn from `Resources/assets` (`cube.gltf` + -`cube_texture.png`); the app rotates it each frame via `sr_set_rotation`. +`cube_texture.png` + `cube_normal.png`); the app rotates it each frame via `sr_set_rotation`. (raylib's `LoadModelAnimations` only handles *skinned* meshes, so a plain node-rotation glTF animation cannot be played by the renderer — hence the cube is app-driven.) `packageMac` bundles `Resources/assets/` into the app. +Shaders and render constants live in **Swift**, not in C: GLSL sources are +`RENDER_SHADER_*` in `components/render/renderConstShader.swift`, and +`RENDER_CONFIG` / `sr_config` tunables are in `renderConst.swift`. `sr_init` +compiles the shaders in place (no storage/`strdup`). `cube_normal.png` drives +tangentless normal mapping via the derivative-based `cotangentFrame`. The +context is OpenGL 3.2 Core (`RENDER_OPENGL_ATTRS`); on Apple Silicon the driver +still reports 4.1/GLSL 4.10. + +## Render architecture + +The `Render` dialect context owns the GL scene. `RenderGLView` is a thin +`NSOpenGLView`; it only translates AppKit callbacks into dialect fields, and the +`render*` files do the actual work. + +1. `AppDelegate` creates `RenderComponent` + `RenderVM` and calls + `render.setup()` -> `didSetup` -> `didLaunch` (should) -> `pixelSize = [1, 1]`. +2. SwiftUI builds `RenderView` -> `RenderGLView`; `prepareOpenGL()` sets + `F.didPrepareGL`. Its oneliners run `renderInit` (`sr_init`), set + `RenderVM.didPrepareGL = true`, and `renderStartTimer`. +3. `reshape()` / `viewDidChangeBackingProperties()` compute the backing pixel + size via `renderPixelSize` and set `F.reshapePixelSize` / + `F.backingPixelSize`. The `pixelSize` shoulds fold these into `F.pixelSize`, + whose oneliner stores `RenderVM.pixelSize`. +4. The timer only sets `needsDisplay` every `1 / RENDER_FPS`. `draw(_:)` forwards + to `renderDraw` (make context current, `sr_resize`, `sr_set_rotation`, + `sr_render`, `flushBuffer`). +5. A button click runs `rootSet(F.didClickIncrement)` -> RootComponent oneliner + `renderSet(F.didClickIncrement)` -> `renderLoadCubeModel` (the cube is loaded + on demand, not at startup). +6. `RenderGLView.deinit` sets `F.willDeinit` -> `renderDeinit` (stop timer, + `sr_shutdown`). + +**GL context rule**: every raylib call must run with the view's context current. +`renderInit`, `renderLoadCubeModel`, `renderDeinit` and `renderDraw` all call +`openGLContext?.makeCurrentContext()` first. Loading a model/texture without it +fails silently with `WARNING: TEXTURE: Failed to load texture`. + ## Build & Run ```bash @@ -161,8 +222,10 @@ The project currently builds in Swift 5 language mode (`util/step/buildMac` has the Swift 6 flag commented out). Enabling `-Xswiftc -swift-version -Xswiftc 6` fails today on the singleton/`@MainActor` concurrency errors (`RootComponent.singleton`, `RootVM.shared` in -`components/root/`, and the `RootVM.shared!.countText = ...` oneliner in the -generated `dialect.swift`). Do not flip it on without addressing those. +`components/root/`, `RenderComponent.singleton`, `RenderVM.shared` in +`components/render/`, and the `RootVM.shared!.countText = ...` / +`RenderVM.shared!.pixelSize = ...` oneliners in the generated `dialect.swift`). +Do not flip it on without addressing those. ## Conventions @@ -171,8 +234,11 @@ generated `dialect.swift`). Do not flip it on without addressing those. - Prefer editing files in `components/` (the real files); the `src/` entries are symlinks. - The generated UI callback plumbing is nonisolated; UI singletons are weak - (`RootComponent.singleton`, `RootVM.shared`) and are accessed from the - generated oneliners with force-unwrap (`RootVM.shared!.countText = ...`). + (`RootComponent.singleton`, `RootVM.shared`, `RenderComponent.singleton`, + `RenderVM.shared`) and are accessed from the generated oneliners with + force-unwrap (`RootVM.shared!.countText = ...`, `RenderVM.shared!.pixelSize = ...`). +- Never call raylib / `sr_*` without making the view's GL context current first + (see the GL context rule above). ## Skill: source-file study documents @@ -184,5 +250,7 @@ fix) — follow the skill in `docs/file-summary.md`. - Write the result to `docs/.html` (e.g. `docs/RaylibGLView.html`) and name the file's Git revision in the header. The file is the source of truth — document the exact revision requested, not the working tree. -- Existing example: `docs/RaylibGLView.html` (single-cube `RaylibGLView.swift`). +- Existing example: `docs/RaylibGLView.html` — documents the historical + single-cube `RaylibGLView.swift`, since split into `RenderGLView.swift` plus + the `render*` files. diff --git a/game/ver-mac/Package.swift b/game/ver-mac/Package.swift index 96e5628..6e176d1 100644 --- a/game/ver-mac/Package.swift +++ b/game/ver-mac/Package.swift @@ -1,6 +1,6 @@ // swift-tools-version: 5.9 -import PackageDescription import Foundation +import PackageDescription let raylibPrefix = ProcessInfo.processInfo.environment["RAYLIB_PREFIX"] ?? "/opt/homebrew"