# OGS applications (`mj`) Native SwiftUI applications using the Dialect v4 declarative reactive engine. Version: `2.0.0`. Remote: `https://git.opengamestudio.org/mahjong/mahjong`. ## Current 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. ## Source 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. ## Graphics ownership and platform differences 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. 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`. 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. 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 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 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)`. ```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): ```sh find components ogs-blue ogs-chkgfx ogs-mahjong -type l ! -exec test -e {} \; -not -path '*/.build/*' ``` ## 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. ## 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. ## Conventions - `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.