Files
__mahjong/AGENTS.md
T
2026-10-31 23:04:43 +03:00

4.6 KiB

OGS applications (mj)

Native SwiftUI apps on the Dialect v4 declarative reactive engine (v2.0.0). Remote: https://git.opengamestudio.org/mahjong/mahjong.

Status

  • ogs-blue/ — active minimal example (macOS + iOS): solid blue raylib background under a SwiftUI overlay; no model/texture/shadow scene.
  • ogs-mahjong/ — macOS scaffold + counter template; no gameplay.
  • ogs-chkgfx/ — companion graphics scaffold; targets lag shared-component changes.
  • game/ver-mac and the root dialect.yml layout are obsolete.

Layout

  • <app>/dialect.yml → <app>/ver-mac/src/dialect.swift (Blue iOS links to it).
  • components/ — shared source of truth; app src/ entries are relative symlinks: edit the real files and keep symlink parity.
  • components/render/ — shared model/constants + mirrored ios//mac/ effects, helpers, views (renderConstMac.swift = native pixel format).
  • Single-header C: raybri/raybri.h (RAYBRI_IMPLEMENTATION) + raybriConst.h + mac/raybriAux.h; egl/egl.h (EGL_IMPLEMENTATION) + eglConst.h; ogs-blue/ver-{mac,ios}/src/Blue.c are the platform translation units.
  • history/gitjs/ — historical JS reference, outside the build.

GL rules

Never call raylib / raybri_* without making the view's GL context current on the calling thread; rlLoadExtensions needs a current context and precedes rlglInit.

macOS: NSOpenGLView (3.2 Core); renderInit makes it current, enables VSync, loads extensions via the C loader, starts raylib. Timer → needsDisplay; draw(_:) → renderDraw activates the context, renders, flushBuffers.

iOS: RenderGLView.st owns an EGLState; effects create EGL/ANGLE state and surface, make it current, init raylib. Timer renders directly, eglSwapBuffers presents. Resize → renderRecreateSurface (macOS no-op). Teardown: stop timer → activate context → release rlgl → destroy EGL surface/context/display.

Blue iOS bridges via src/BlueBridgingHeader.h; Blue.c compiles EGL helpers and rlgl with their implementation macros once, uses raylib-iOS XCFramework headers but not its library, links/embeds ANGLE libEGL + libGLESv2. XcodeGen sets PLATFORM_IOS, GRAPHICS_API_OPENGL_ES3, GL_GLEXT_PROTOTYPES; min iOS 15.0. SPM target RaylibBridge compiles src/Blue.c, exposes src/raybri headers, links Homebrew raylib but NOT RLGL_IMPLEMENTATION (headers lack external/glad.h).

Build

Prereqs: brew install raylib xcodegen; siblings ../dialect (util/build-generator) and ../raylib-ios-xcframeworks (raylib + libEGL/libGLESv2; presence checked only).

util/build-ogs-blue-mac
util/run-ogs-blue-mac
util/prepare-ogs-blue-ios
xcodebuild -project 'ogs-blue/ver-ios/OGS blue.xcodeproj' -scheme ogs-blue \
  -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' \
  CODE_SIGNING_ALLOWED=NO build

macOS scripts regenerate Dialect, swift build, then package ver-mac/res/ into ver-mac/.build/<App Name>.app. iOS also checks XCFrameworks, stages ANGLE symlinks in ver-ios/.build/, then runs XcodeGen (same scripts for ogs-chkgfx/ogs-mahjong). Dangling-symlink audit: find components ogs-blue ogs-chkgfx ogs-mahjong -type l ! -exec test -e {} \; -not -path '*/.build/*'

Dialect

  • Edit <app>/dialect.yml / components/, then util/build-<app>-mac; manual edits to the generated dialect.swift are overwritten.
  • struct F (field names) exists only in dialect.swift: a new field needs static let <field> = "<field>" hand-patched in ASCII order or F.<field> won't build.
  • Validate: ruby -ryaml -e 'YAML.load_file("ogs-blue/dialect.yml")'. Every should-label (1. Upon each ...) MUST end with a colon — components/yml/ymlFun.swift blindly dropLast()s it. Complaints inside if:/then: (unquoted : ) are expected.

Conventions

  • Mirror Swift/iOS into Android (naming, text, layout, styling); OGS blue, not OGS Blue.
  • Compose: named MaterialTheme.typography styles over fontSize; Blue's title is headlineLarge (SwiftUI .largeTitle).
  • Kotlin: wildcard imports for multiple declarations from one package, including generated ones; subpackages need separate imports.
  • .build/, build/, .DS_Store, Xcode/Gradle artifacts are git-ignored.

Source studies

Follow docs/file-summary.md (single-file) and docs/mirror-summary.md (mirrored platforms: one self-contained HTML with aligned function starts, original line numbers, green/orange fills, counts, non-repetitive explanations). Example: docs/render-platform-comparison.html; never substitute working-tree code for a requested historical revision.