diff --git a/AGENTS.md b/AGENTS.md index 87d4048..e48e75b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,176 +1,100 @@ # OGS applications (`mj`) -Native SwiftUI applications using the Dialect v4 declarative reactive engine. -Version: `2.0.0`. Remote: `https://git.opengamestudio.org/mahjong/mahjong`. +Native SwiftUI apps on the Dialect v4 declarative reactive engine (v2.0.0). +Remote: `https://git.opengamestudio.org/mahjong/mahjong`. -## Current status +## Status -- `ogs-blue/` is the active minimal graphics example for macOS and iOS: a solid - blue raylib background with a SwiftUI overlay. It has no model/texture/shadow - scene; rlgl still creates its default internal GPU resources. -- `ogs-mahjong/` contains the macOS Mahjong scaffold and counter-template logic; - Mahjong gameplay has not been implemented. -- `ogs-chkgfx/` is a companion graphics scaffold with macOS/iOS project files. - Older targets can lag behind shared-component changes; verify each target - separately before claiming it builds. -- The previous `game/ver-mac` and root `dialect.yml` layout is obsolete. +- `ogs-blue/` — active minimal example (macOS + iOS): solid blue raylib background + under a SwiftUI overlay; no model/texture/shadow scene. +- `ogs-mahjong/` — macOS scaffold + counter template; no gameplay. +- `ogs-chkgfx/` — companion graphics scaffold; targets lag shared-component changes. +- `game/ver-mac` and the root `dialect.yml` layout are obsolete. -## Source layout +## Layout -- `/dialect.yml`: per-application logic; generates - `/ver-mac/src/dialect.swift`. Blue iOS links to its macOS generated file. -- `components/`: shared source of truth. App `src/` files use relative symlinks; - edit real component files and preserve symlink parity. -- `components/render/`: shared component/model/constants, plus mirrored `ios/` - and `mac/` effects, helpers and native/SwiftUI views. macOS additionally has - `renderConstMac.swift` for native pixel-format attributes. -- `components/raybri/raybri.h`: declarations plus implementation gated by - `RAYBRI_IMPLEMENTATION`; clears blue, renders and shuts down rlgl. -- `components/raybri/raybriConst.h`: shared constants with an implementation macro. - `components/raybri/mac/raybriAux.h`: macOS OpenGL symbol loader. -- `components/egl/egl.h` and `eglConst.h`: EGL state/helpers and configuration, - using single-header implementation macros. -- `ogs-blue/ver-{mac,ios}/src/Blue.c`: platform C implementation translation units. -- `history/gitjs/`: historical JavaScript Mahjong reference, outside the build. - `ref/swiftraylib` links to the sibling renderer sample. +- `/dialect.yml` → `/ver-mac/src/dialect.swift` (Blue iOS links to it). +- `components/` — shared source of truth; app `src/` entries are relative symlinks: + edit the real files and keep symlink parity. +- `components/render/` — shared model/constants + mirrored `ios/`/`mac/` effects, + helpers, views (`renderConstMac.swift` = native pixel format). +- Single-header C: `raybri/raybri.h` (`RAYBRI_IMPLEMENTATION`) + `raybriConst.h` + + `mac/raybriAux.h`; `egl/egl.h` (`EGL_IMPLEMENTATION`) + `eglConst.h`; + `ogs-blue/ver-{mac,ios}/src/Blue.c` are the platform translation units. +- `history/gitjs/` — historical JS reference, outside the build. -## Graphics ownership and platform differences +## GL rules -Every GPU operation requires its context current on the calling thread. -`rlLoadExtensions` also requires an existing current context; it precedes -`rlglInit`, not native context creation. +Never call raylib / `raybri_*` without making the view's GL context current on the +calling thread; `rlLoadExtensions` needs a current context and precedes `rlglInit`. -macOS uses `NSOpenGLView` (OpenGL 3.2 Core). `renderInit` makes its context -current, enables VSync, loads extensions with the C loader callback and starts -raylib. The timer requests `needsDisplay`; `draw(_:)` forwards to `renderDraw`, -which activates the context, renders and presents via `flushBuffer`. +macOS: `NSOpenGLView` (3.2 Core); `renderInit` makes it current, enables VSync, loads +extensions via the C loader, starts raylib. Timer → `needsDisplay`; `draw(_:)` → +`renderDraw` activates the context, renders, `flushBuffer`s. -Blue's SPM `RaylibBridge` target compiles `src/Blue.c`, exposes headers in -`src/raybri`, and links Homebrew raylib. It does NOT define -`RLGL_IMPLEMENTATION`: Homebrew headers omit the `external/glad.h` needed to -compile desktop rlgl locally. Swift imports `RaylibBridge`. `RAYLIB_PREFIX` -defaults to `/opt/homebrew`; build scripts detect `brew --prefix raylib`. -The installed raylib may produce a deployment-target linker warning. +iOS: `RenderGLView.st` owns an `EGLState`; effects create EGL/ANGLE state and surface, +make it current, init raylib. Timer renders directly, `eglSwapBuffers` presents. +Resize → `renderRecreateSurface` (macOS no-op). Teardown: stop timer → activate +context → release rlgl → destroy EGL surface/context/display. -On iOS, UIKit owns the view/layer and `RenderGLView.st` owns an `EGLState`. -Swift effects create EGL/ANGLE state and surface, make the context current, -and initialize raylib. Timer ticks call rendering directly; presentation uses -`eglSwapBuffers`. Pixel sizes come from view bounds and content scale. -Dialect's resize event triggers `renderRecreateSurface`; the macOS helper is -intentionally a no-op. Teardown must stop the timer, activate the context, -release rlgl resources, then destroy EGL surface/context/display resources. +Blue iOS bridges via `src/BlueBridgingHeader.h`; `Blue.c` compiles EGL helpers and rlgl +with their implementation macros once, uses raylib-iOS XCFramework headers but not its +library, links/embeds ANGLE `libEGL` + `libGLESv2`. XcodeGen sets `PLATFORM_IOS`, +`GRAPHICS_API_OPENGL_ES3`, `GL_GLEXT_PROTOTYPES`; min iOS 15.0. SPM target +`RaylibBridge` compiles `src/Blue.c`, exposes `src/raybri` headers, links Homebrew +raylib but NOT `RLGL_IMPLEMENTATION` (headers lack `external/glad.h`). -Blue iOS uses `src/BlueBridgingHeader.h` to expose C APIs to Swift. `Blue.c` -compiles EGL helpers and rlgl using their implementation macros exactly once. -It uses the raylib-iOS XCFramework headers but does not link its full raylib -library. The app links/embeds `libEGL` and `libGLESv2` (ANGLE's Metal backend). -The XcodeGen settings define `PLATFORM_IOS`, `GRAPHICS_API_OPENGL_ES3`, and -`GL_GLEXT_PROTOTYPES`. Minimum iOS is 15.0; portrait and both landscape -orientations are enabled in Blue's Info.plist. +## Build -## Build and prerequisites - -- macOS: `brew install raylib`. -- iOS project generation: `brew install xcodegen`; supply sibling - `../raylib-ios-xcframeworks` containing raylib/libEGL/libGLESv2 XCFrameworks. - `checkRaylibIOS` checks presence; it does not download them. -- Dialect: sibling `../dialect`, built with `(cd ../dialect && util/build-generator)`. +Prereqs: `brew install raylib xcodegen`; siblings `../dialect` (`util/build-generator`) +and `../raylib-ios-xcframeworks` (raylib + libEGL/libGLESv2; presence checked only). ```sh util/build-ogs-blue-mac util/run-ogs-blue-mac util/prepare-ogs-blue-ios -``` - -The corresponding macOS build/run scripts also exist for `ogs-chkgfx` and -`ogs-mahjong`; `prepare-ogs-chkgfx-ios` exists as well. Inspect their individual -configuration before assuming parity with Blue. - -macOS build scripts generate Dialect, run `swift build`, and package resources -from `ver-mac/res/` into `ver-mac/.build/.app`. iOS preparation checks -XCFrameworks, generates Dialect, stages ANGLE include/library symlinks in -`ver-ios/.build/`, then runs XcodeGen. Build Blue for Simulator with: - -```sh xcodebuild -project 'ogs-blue/ver-ios/OGS blue.xcodeproj' -scheme ogs-blue \ -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' \ CODE_SIGNING_ALLOWED=NO build ``` -Audit dangling source symlinks after moves (SPM can silently skip them): +macOS scripts regenerate Dialect, `swift build`, then package `ver-mac/res/` into +`ver-mac/.build/.app`. iOS also checks XCFrameworks, stages ANGLE symlinks in +`ver-ios/.build/`, then runs XcodeGen (same scripts for `ogs-chkgfx`/`ogs-mahjong`). +Dangling-symlink audit: +`find components ogs-blue ogs-chkgfx ogs-mahjong -type l ! -exec test -e {} \; -not -path '*/.build/*'` -```sh -find components ogs-blue ogs-chkgfx ogs-mahjong -type l ! -exec test -e {} \; -not -path '*/.build/*' -``` +## Dialect -## Editing the dialect - -- Add/modify contexts and components in `/dialect.yml`, then run - `util/build--mac` to regenerate `dialect.swift`. -- **Chicken-egg**: `struct F` (field-name constants) lives only in the - generated `dialect.swift`. Adding a new field to a context in `/dialect.yml` - requires hand-patching its `static let = ""` into `struct F` - in `dialect.swift` (ASCII-alphabetical order) if you cannot regenerate first, - otherwise the build fails on `F.` being unresolved. -- `dialect.swift` is generated — edits there are overwritten on the next - `util/build--mac`. Change the source (`/dialect.yml` / `components/`) instead. -- **Validate `/dialect.yml` after edits** (e.g. `ruby -ryaml -e 'YAML.load_file("ogs-blue/dialect.yml")'`). - Every should-branch label (`1. Upon each ...`) MUST end with a colon — the - parser (`components/yml/ymlFun.swift`) blindly `dropLast()`s it, so a missing - colon silently eats the label's last character in the generated `about` - comment. Note the file can never pass a *strict* YAML parser: condition and - reaction lines (under `if:` / `then:`) contain unquoted `: ` (e.g. - `c.countText = "Count: '\(c.count)'"`), which standard YAML rejects. So treat - a parser complaint pointing *inside* an `if:`/`then:` block as expected; any - complaint elsewhere (like a missing branch-label colon) is a real bug. +- Edit `/dialect.yml` / `components/`, then `util/build--mac`; manual edits to + the generated `dialect.swift` are overwritten. +- `struct F` (field names) exists only in `dialect.swift`: a new field needs + `static let = ""` hand-patched in ASCII order or `F.` won't build. +- Validate: `ruby -ryaml -e 'YAML.load_file("ogs-blue/dialect.yml")'`. Every should-label + (`1. Upon each ...`) MUST end with a colon — `components/yml/ymlFun.swift` blindly + `dropLast()`s it. Complaints inside `if:`/`then:` (unquoted `: `) are expected. ## Swift 6 -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/`, `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. +Swift 5 mode today (`util/step/buildMac`); `-swift-version 6` fails on `@MainActor` +singleton errors in `components/root/` and `components/render/` plus the +`RootVM.shared!.countText = ...` oneliners. Don't enable before fixing: the generated +UI callback plumbing is nonisolated and force-unwraps weak singletons. ## Conventions -- When generating or mirroring Swift/iOS code into Android, stay as close to - the Swift original as possible: preserve naming, capitalization, visible text, - layout, styling, behavior and structure. Use the closest platform equivalent - where a direct translation is unavailable; avoid unrelated redesigns or - Android-specific changes unless requested. In particular, use `OGS blue` - (not `OGS Blue`) for the Android project name and app labels, matching iOS. +- Mirror Swift/iOS into Android (naming, text, layout, styling); `OGS blue`, not `OGS Blue`. +- Compose: named `MaterialTheme.typography` styles over `fontSize`; Blue's title is + `headlineLarge` (SwiftUI `.largeTitle`). +- Kotlin: wildcard imports for multiple declarations from one package, including + generated ones; subpackages need separate imports. +- `.build/`, `build/`, `.DS_Store`, Xcode/Gradle artifacts are git-ignored. -- Android Compose typography: prefer named `MaterialTheme.typography` styles - over explicit numeric `fontSize` values. Use `headlineLarge` for Blue's title - as the counterpart to SwiftUI's `.largeTitle`, on both overlaid text layers. +## Source studies -- Android Kotlin imports: use wildcard imports (`package.*`) when importing - multiple declarations from the same package, including newly generated imports. - Keep single imports and aliases explicit where needed to avoid name conflicts. - Wildcards do not include subpackages; import those separately. - -- `game/ver-mac/.build/`, `build/`, `.DS_Store`, Xcode/Gradle artifacts are - git-ignored. -- 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`, `RenderComponent.singleton`, - `RenderVM.shared`) and are accessed from the generated oneliners with - force-unwrap (`RootVM.shared!.countText = ...`, `RenderVM.shared!.pixelSize = ...`). -- Never call raylib / `raybri_*` without making the view's GL context current first - (see the GL context rule above). - -## Source study documents - -- Single-file source studies: follow [docs/file-summary.md](docs/file-summary.md). -- Mirrored platform studies: follow [docs/mirror-summary.md](docs/mirror-summary.md). - Produce one self-contained downloadable HTML with aligned function starts, - original line numbers, green/orange number fills, counts/percentages and a - non-repetitive explanation column. -- Existing mirrored example: `docs/render-platform-comparison.html`, documenting - the revision named in its header. Never silently substitute working-tree code - for a requested historical revision. +Follow [docs/file-summary.md](docs/file-summary.md) (single-file) and +[docs/mirror-summary.md](docs/mirror-summary.md) (mirrored platforms: one +self-contained HTML with aligned function starts, original line numbers, green/orange +fills, counts, non-repetitive explanations). Example: +`docs/render-platform-comparison.html`; never substitute working-tree code for a +requested historical revision.