Files
2026-10-30 15:17:24 +01:00

8.3 KiB

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

  • <app>/dialect.yml: per-application logic; generates <app>/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).
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 Name>.app. iOS preparation checks XCFrameworks, generates Dialect, stages ANGLE include/library symlinks in ver-ios/.build/, then runs XcodeGen. Build Blue for Simulator with:

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):

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 <app>/dialect.yml, then run util/build-<app>-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 <app>/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-<app>-mac. Change the source (<app>/dialect.yml / components/) instead.
  • Validate <app>/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.
  • Mirrored platform studies: follow 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.