# OGS applications (`mj`) Native SwiftUI apps on the Dialect v4 declarative reactive engine (v2.0.0). Remote: `https://git.opengamestudio.org/mahjong/mahjong`. ## Status - `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. ## Layout - `/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. ## GL rules 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: `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. 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. 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`). ## Build 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 xcodebuild -project 'ogs-blue/ver-ios/OGS blue.xcodeproj' -scheme ogs-blue \ -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' \ CODE_SIGNING_ALLOWED=NO build ``` 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/*'` ## Dialect - 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 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 - 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. ## Source studies 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.