Files
__mahjong/AGENTS.md
T
2026-10-23 06:45:53 +03:00

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.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.

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:

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.

  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

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.