some
This commit is contained in:
1 parent
d11461c5ae
commit
37c6950503
1 file changed
+67
-143
@@ -1,176 +1,100 @@
|
||||
# OGS applications (`mj`)
|
||||
|
||||
Native SwiftUI applications using the Dialect v4 declarative reactive engine.
|
||||
Version: `2.0.0`. Remote: `https://git.opengamestudio.org/mahjong/mahjong`.
|
||||
Native SwiftUI apps on the Dialect v4 declarative reactive engine (v2.0.0).
|
||||
Remote: `https://git.opengamestudio.org/mahjong/mahjong`.
|
||||
|
||||
## Current status
|
||||
## 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.
|
||||
- `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.
|
||||
|
||||
## Source layout
|
||||
## 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.
|
||||
- `<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.
|
||||
|
||||
## Graphics ownership and platform differences
|
||||
## GL rules
|
||||
|
||||
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.
|
||||
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 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`.
|
||||
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, `flushBuffer`s.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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 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`).
|
||||
|
||||
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
|
||||
|
||||
## 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)`.
|
||||
Prereqs: `brew install raylib xcodegen`; siblings `../dialect` (`util/build-generator`)
|
||||
and `../raylib-ios-xcframeworks` (raylib + libEGL/libGLESv2; presence checked only).
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```sh
|
||||
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):
|
||||
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/*'`
|
||||
|
||||
```sh
|
||||
find components ogs-blue ogs-chkgfx ogs-mahjong -type l ! -exec test -e {} \; -not -path '*/.build/*'
|
||||
```
|
||||
## Dialect
|
||||
|
||||
## 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.
|
||||
- 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.
|
||||
|
||||
## 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.
|
||||
Swift 5 mode today (`util/step/buildMac`); `-swift-version 6` fails on `@MainActor`
|
||||
singleton errors in `components/root/` and `components/render/` plus the
|
||||
`RootVM.shared!.countText = ...` oneliners. Don't enable before fixing: the generated
|
||||
UI callback plumbing is nonisolated and force-unwraps weak singletons.
|
||||
|
||||
## Conventions
|
||||
|
||||
- When generating or mirroring Swift/iOS code into Android, stay as close to
|
||||
the Swift original as possible: preserve naming, capitalization, visible text,
|
||||
layout, styling, behavior and structure. Use the closest platform equivalent
|
||||
where a direct translation is unavailable; avoid unrelated redesigns or
|
||||
Android-specific changes unless requested. In particular, use `OGS blue`
|
||||
(not `OGS Blue`) for the Android project name and app labels, matching iOS.
|
||||
- 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.
|
||||
|
||||
- Android Compose typography: prefer named `MaterialTheme.typography` styles
|
||||
over explicit numeric `fontSize` values. Use `headlineLarge` for Blue's title
|
||||
as the counterpart to SwiftUI's `.largeTitle`, on both overlaid text layers.
|
||||
## Source studies
|
||||
|
||||
- Android Kotlin imports: use wildcard imports (`package.*`) when importing
|
||||
multiple declarations from the same package, including newly generated imports.
|
||||
Keep single imports and aliases explicit where needed to avoid name conflicts.
|
||||
Wildcards do not include subpackages; import those separately.
|
||||
|
||||
- `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](docs/file-summary.md).
|
||||
- Mirrored platform studies: follow [docs/mirror-summary.md](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.
|
||||
Follow [docs/file-summary.md](docs/file-summary.md) (single-file) and
|
||||
[docs/mirror-summary.md](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.
|
||||
Reference in new issue
Block a user