263 lines
14 KiB
Markdown
263 lines
14 KiB
Markdown
# OGS Mahjong (`mj`)
|
|
|
|
A macOS SwiftUI app for **OGS Mahjong**, built on the **Dialect v4** declarative
|
|
reactive engine (see the sibling `../dialect` repo — this project is a
|
|
downstream consumer of its code generator).
|
|
|
|
Business logic lives in `dialect.yml` (YAML). A generator turns it into
|
|
`game/ver-mac/src/dialect.swift` (the runtime engine + `struct F` field
|
|
constants + component/should/effect registration). The Swift app shell
|
|
(`GameApp`/`AppDelegate`) and the SwiftUI views live outside the generated file
|
|
and talk to the engine through generated functions like `rootSet(...)`.
|
|
|
|
Remote: `https://git.opengamestudio.org/mahjong/mahjong` · Version: `2.0.0`
|
|
|
|
> `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
|
|
|
|
```
|
|
dialect.yml Single source of truth for the reactive logic.
|
|
Generates game/ver-mac/src/dialect.swift
|
|
|
|
components/ SHARED source-of-truth for all components.
|
|
other/other.swift Shared helpers (otherPrintStderr, otherWriteFile,
|
|
otherSetupConsoleLogging, ...)
|
|
raybri/raybri.h C API of the raylib bridge (raybri_config, raybri_init,
|
|
raybri_load_model, raybri_resize, raybri_set_rotation,
|
|
raybri_render, raybri_shutdown); extern "C" guards.
|
|
raybri/raybri.c Bridge implementation: rlgl scene, shadow pass, shaders.
|
|
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 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 (raybri_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); C target
|
|
"RaylibBridge" (path src/raybri, publicHeadersPath ".") +
|
|
links Homebrew raylib; the Swift target excludes raybri
|
|
and 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, cube_normal.png
|
|
src/
|
|
GameApp.swift @main SwiftUI App entry
|
|
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
|
|
raybri/raybri.c -> symlink components/raybri/raybri.c
|
|
raybri/raybri.h -> symlink components/raybri/raybri.h
|
|
render/render.swift -> symlink components/render/render.swift
|
|
render/renderAux.swift -> symlink components/render/mac/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.
|
|
|
|
util/ Build/run scripts (see Build & Run)
|
|
paths APP_MAC = .build/OGS Mahjong.app
|
|
build-mac generateDialect -> buildMac -> packageMac
|
|
run-mac runMac
|
|
rm-mac-geom Resets saved window geometry
|
|
step/ Sourced steps: generateDialect, buildMac,
|
|
packageMac, runMac
|
|
|
|
history/gitjs/ GitJS "Glavred" history + the original JS source of the
|
|
web Mahjong, kept for reference — not part of the build.
|
|
```
|
|
|
|
## Symlink parity rule
|
|
|
|
`components/` is the source of truth; `game/ver-mac/src/` contains real
|
|
directories whose files are **relative symlinks** back into `components/`:
|
|
|
|
```
|
|
src/other/other.swift -> ../../../../components/other/other.swift (4 up)
|
|
src/raybri/raybri.c -> ../../../../components/raybri/raybri.c (4 up)
|
|
src/raybri/raybri.h -> ../../../../components/raybri/raybri.h (4 up)
|
|
src/render/render.swift -> ../../../../components/render/render.swift (4 up)
|
|
src/render/renderAux.swift -> ../../../../components/render/mac/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)
|
|
src/render/view/RenderGLView.swift -> ../../../../../components/render/mac/view/RenderGLView.swift (5 up)
|
|
src/render/view/RenderView.swift -> ../../../../../components/render/mac/view/RenderView.swift (5 up)
|
|
```
|
|
|
|
SPM silently **skips** a dangling symlink (no error), so after moving
|
|
`components/` or a subdir, audit for broken links:
|
|
|
|
```bash
|
|
find . -type l ! -exec test -e {} \; -not -path './.build/*'
|
|
```
|
|
|
|
## Prerequisite: the generator
|
|
|
|
`util/step/generateDialect` calls the **sibling** dialect repo:
|
|
|
|
```bash
|
|
$SDIR/../../dialect/util/run-generator --file=$SDIR/../dialect.yml
|
|
```
|
|
|
|
So `/Volumes/MOE/p/dialect` must exist and its generator must be built before
|
|
`util/build-mac` can regenerate:
|
|
|
|
```bash
|
|
(cd ../dialect && util/build-generator) # once, or after dialect core changes
|
|
```
|
|
|
|
The generator resolves the `output:` path **relative to `dialect.yml`'s
|
|
directory**, which is why `dialect.yml` says `game/ver-mac/src/dialect.swift`.
|
|
|
|
## Prerequisite: raylib
|
|
|
|
The 3D scene links against Homebrew **raylib** (`brew install raylib`). The
|
|
`RaylibBridge` C target and the link step read `RAYLIB_PREFIX` (default
|
|
`/opt/homebrew`); `util/step/buildMac` auto-detects it via `brew --prefix raylib`.
|
|
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` + `cube_normal.png`); the app rotates it each frame via `raybri_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` / `raybri_config` tunables are in `renderConst.swift`. `raybri_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` (`raybri_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, `raybri_resize`, `raybri_set_rotation`,
|
|
`raybri_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,
|
|
`raybri_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
|
|
util/build-mac # generateDialect + swift build + package OGS Mahjong.app
|
|
util/run-mac # runs .build/OGS Mahjong.app/Contents/MacOS/ogs-mahjong
|
|
util/rm-mac-geom # reset the app's saved window geometry
|
|
```
|
|
|
|
`build-mac` sources `util/paths` then the `util/step/*` scripts in order:
|
|
|
|
1. `generateDialect` — runs the sibling generator, writes `src/dialect.swift`
|
|
2. `buildMac` — `brew --prefix raylib` -> `RAYLIB_PREFIX`, `swift build`
|
|
3. `packageMac` — assembles `.build/OGS Mahjong.app` (binary `ogs-mahjong`,
|
|
`Info.plist`, `Resources/AppIcon.icns`, `Resources/assets/`)
|
|
|
|
## 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 <field> = "<field>"` into `struct F`
|
|
in `dialect.swift` (ASCII-alphabetical order) if you cannot regenerate first,
|
|
otherwise the build fails on `F.<field>` 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("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).
|
|
|
|
## Skill: source-file study documents
|
|
|
|
When the task is to produce a source-code study document — a self-contained,
|
|
downloadable HTML file with a line-by-line table of the file and its
|
|
explanations (and, on request, a second version highlighting changes after a
|
|
fix) — follow the skill in `docs/file-summary.md`.
|
|
|
|
- Write the result to `docs/<FileName>.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` — documents the historical
|
|
single-cube `RaylibGLView.swift`, since split into `RenderGLView.swift` plus
|
|
the `render*` files.
|
|
|