14 KiB
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.ymlis still the "Root / counter" template with aRendercontext 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/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/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:
find . -type l ! -exec test -e {} \; -not -path './.build/*'
Prerequisite: the generator
util/step/generateDialect calls the sibling dialect repo:
$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:
(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.
AppDelegatecreatesRenderComponent+RenderVMand callsrender.setup()->didSetup->didLaunch(should) ->pixelSize = [1, 1].- SwiftUI builds
RenderView->RenderGLView;prepareOpenGL()setsF.didPrepareGL. Its oneliners runrenderInit(raybri_init), setRenderVM.didPrepareGL = true, andrenderStartTimer. reshape()/viewDidChangeBackingProperties()compute the backing pixel size viarenderPixelSizeand setF.reshapePixelSize/F.backingPixelSize. ThepixelSizeshoulds fold these intoF.pixelSize, whose oneliner storesRenderVM.pixelSize.- The timer only sets
needsDisplayevery1 / RENDER_FPS.draw(_:)forwards torenderDraw(make context current,raybri_resize,raybri_set_rotation,raybri_render,flushBuffer). - A button click runs
rootSet(F.didClickIncrement)-> RootComponent onelinerrenderSet(F.didClickIncrement)->renderLoadCubeModel(the cube is loaded on demand, not at startup). RenderGLView.deinitsetsF.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
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:
generateDialect— runs the sibling generator, writessrc/dialect.swiftbuildMac—brew --prefix raylib->RAYLIB_PREFIX,swift buildpackageMac— assembles.build/OGS Mahjong.app(binaryogs-mahjong,Info.plist,Resources/AppIcon.icns,Resources/assets/)
Editing the dialect
- Add/modify contexts and components in
dialect.yml, then runutil/build-macto regeneratedialect.swift. - Chicken-egg:
struct F(field-name constants) lives only in the generateddialect.swift. Adding a new field to a context indialect.ymlrequires hand-patching itsstatic let <field> = "<field>"intostruct Findialect.swift(ASCII-alphabetical order) if you cannot regenerate first, otherwise the build fails onF.<field>being unresolved. dialect.swiftis generated — edits there are overwritten on the nextutil/build-mac. Change the source (dialect.yml/components/) instead.- Validate
dialect.ymlafter 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) blindlydropLast()s it, so a missing colon silently eats the label's last character in the generatedaboutcomment. Note the file can never pass a strict YAML parser: condition and reaction lines (underif:/then:) contain unquoted:(e.g.c.countText = "Count: '\(c.count)'"), which standard YAML rejects. So treat a parser complaint pointing inside anif:/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); thesrc/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-cubeRaylibGLView.swift, since split intoRenderGLView.swiftplus therender*files.