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-macand rootdialect.ymllayout 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. Appsrc/files use relative symlinks; edit real component files and preserve symlink parity.components/render/: shared component/model/constants, plus mirroredios/andmac/effects, helpers and native/SwiftUI views. macOS additionally hasrenderConstMac.swiftfor native pixel-format attributes.components/raybri/raybri.h: declarations plus implementation gated byRAYBRI_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.handeglConst.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/swiftrayliblinks 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-xcframeworkscontaining raylib/libEGL/libGLESv2 XCFrameworks.checkRaylibIOSchecks 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 runutil/build-<app>-macto regeneratedialect.swift. - Chicken-egg:
struct F(field-name constants) lives only in the generateddialect.swift. Adding a new field to a context in<app>/dialect.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-<app>-mac. Change the source (<app>/dialect.yml/components/) instead.- Validate
<app>/dialect.ymlafter 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) 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).
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.