Create hello-platform for iOS (#11)

Co-authored-by: Михаил Капелько <kornerr@gmail.com>
This commit is contained in:
kornerr authored and Михаил Капелько committed 2026-11-01 07:19:54 +01:00
1 parent 1aa218d0bb
commit cf79e89dc4
18 files changed
+288 -57

No files matched your search

+31 -56
View File
@@ -3,82 +3,58 @@
Native SwiftUI apps on the Dialect v4 declarative reactive engine (v2.0.0). Native SwiftUI apps on the Dialect v4 declarative reactive engine (v2.0.0).
Remote: `https://git.opengamestudio.org/mahjong/mahjong`. Remote: `https://git.opengamestudio.org/mahjong/mahjong`.
## Status ## Apps
- `ogs-blue/` — active minimal example (macOS + iOS): solid blue raylib background - `hello/hello-platform/` — macOS + iOS platform-support sample (Hello counter). Its
under a SwiftUI overlay; no model/texture/shadow scene. structure, startup flow and dialect rules are in
- `ogs-mahjong/` — macOS scaffold + counter template; no gameplay. [docs/hello-platform.md](docs/hello-platform.md); read that file whenever anything
- `ogs-chkgfx/` — companion graphics scaffold; targets lag shared-component changes. from hello-platform is referenced.
- `game/ver-mac` and the root `dialect.yml` layout are obsolete.
## Layout ## Layout
- `<app>/dialect.yml` → `<app>/ver-mac/src/dialect.swift` (Blue iOS links to it). - `<app>/dialect.yml` → generates `<app>/ver-mac/src/dialect.swift`.
- `components/` — shared source of truth; app `src/` entries are relative symlinks: - `components/` — shared source of truth; app `src/` entries are relative symlinks:
edit the real files and keep symlink parity. edit the real files and keep symlink parity.
- `components/render/` — shared model/constants + mirrored `ios/`/`mac/` effects, - `hello-platform` uses `components/hp/` for its component, view model and shared
helpers, views (`renderConstMac.swift` = native pixel format). SwiftUI view, and `components/other/` for shared helpers.
- 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. - `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, `flushBuffer`s.
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 ## Build
Prereqs: `brew install raylib xcodegen`; siblings `../dialect` (`util/build-generator`) Prereqs: sibling `../dialect` checkout (`util/build-generator`).
and `../raylib-ios-xcframeworks` (raylib + libEGL/libGLESv2; presence checked only).
```sh ```sh
util/build-ogs-blue-mac cd hello/hello-platform
util/run-ogs-blue-mac util/build-mac
util/prepare-ogs-blue-ios util/run-mac
xcodebuild -project 'ogs-blue/ver-ios/OGS blue.xcodeproj' -scheme ogs-blue \ util/prepare-ios # xcodegen; xcodebuild command is in docs/hello-platform.md
-sdk iphonesimulator -destination 'generic/platform=iOS Simulator' \
CODE_SIGNING_ALLOWED=NO build
``` ```
macOS scripts regenerate Dialect, `swift build`, then package `ver-mac/res/` into `build-mac` regenerates Dialect, runs `swift build` in `ver-mac/`, then packages the
`ver-mac/.build/<App Name>.app`. iOS also checks XCFrameworks, stages ANGLE symlinks in binary and `ver-mac/res/` into `ver-mac/.build/<App Name>.app`. `ver-ios/` mirrors
`ver-ios/.build/`, then runs XcodeGen (same scripts for `ogs-chkgfx`/`ogs-mahjong`). `ver-mac/` and shares `dialect.swift`, `HPView` and the app icon via symlinks.
Dangling-symlink audit: Dangling-symlink audit:
`find components ogs-blue ogs-chkgfx ogs-mahjong -type l ! -exec test -e {} \; -not -path '*/.build/*'` `find components hello -type l ! -exec test -e {} \; -not -path '*/.build/*'`
iOS simulator: use **IVA** (`EB867790-F2C0-4392-9F99-C509D4487FDA`, iPhone 17,
iOS 26.5), not iPhone 15 Pro.
## Dialect ## Dialect
- Edit `<app>/dialect.yml` / `components/`, then `util/build-<app>-mac`; manual edits to - Edit `<app>/dialect.yml` / `components/`, then `util/build-mac`; manual edits to the
the generated `dialect.swift` are overwritten. generated `dialect.swift` are overwritten.
- `struct F` (field names) exists only in `dialect.swift`: a new field needs - `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. `static let <field> = "<field>"` hand-patched in ASCII order or `F.<field>`
- Validate: `ruby -ryaml -e 'YAML.load_file("ogs-blue/dialect.yml")'`. Every should-label will not build.
(`1. Upon each ...`) MUST end with a colon — `components/yml/ymlFun.swift` blindly - Validate: `ruby -ryaml -e 'YAML.load_file("hello/hello-platform/dialect.yml")'`.
`dropLast()`s it. Complaints inside `if:`/`then:` (unquoted `: `) are expected. Every should-label (`1. Upon each ...`) MUST end with a colon —
`../dialect/components/yml/ymlFun.swift` blindly `dropLast()`s it. Complaints
inside `if:`/`then:` (unquoted `: `) are expected.
## Conventions ## Conventions
- Mirror Swift/iOS into Android (naming, text, layout, styling); `OGS blue`, not `OGS Blue`. - Mirror Swift/iOS into Android (naming, text, layout, styling).
- Compose: named `MaterialTheme.typography` styles over `fontSize`; Blue's title is - Compose: named `MaterialTheme.typography` styles over `fontSize`.
`headlineLarge` (SwiftUI `.largeTitle`).
- Kotlin: wildcard imports for multiple declarations from one package, including - Kotlin: wildcard imports for multiple declarations from one package, including
generated ones; subpackages need separate imports. generated ones; subpackages need separate imports.
- `.build/`, `build/`, `.DS_Store`, Xcode/Gradle artifacts are git-ignored. - `.build/`, `build/`, `.DS_Store`, Xcode/Gradle artifacts are git-ignored.
@@ -88,6 +64,5 @@ Dangling-symlink audit:
Follow [docs/file-summary.md](docs/file-summary.md) (single-file) and Follow [docs/file-summary.md](docs/file-summary.md) (single-file) and
[docs/mirror-summary.md](docs/mirror-summary.md) (mirrored platforms: one [docs/mirror-summary.md](docs/mirror-summary.md) (mirrored platforms: one
self-contained HTML with aligned function starts, original line numbers, green/orange self-contained HTML with aligned function starts, original line numbers, green/orange
fills, counts, non-repetitive explanations). Example: fills, counts, non-repetitive explanations); never substitute working-tree code for a
`docs/render-platform-comparison.html`; never substitute working-tree code for a
requested historical revision. requested historical revision.
+1 -1
View File
@@ -15,4 +15,4 @@
| Name | Description | macOS | iOS | Android | Linux | Windows | Raspberry Pi | | Name | Description | macOS | iOS | Android | Linux | Windows | Raspberry Pi |
| --- | --- | --- | --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- | --- | --- | --- |
| hp | **hello-platform** is a simple UI to validate platform support | √ | | | | | | | hp | **hello-platform** is a simple UI to validate platform support | √ | √ | | | | |
+1
View File
@@ -0,0 +1 @@
../../../hp/mac/view/HPView.swift
+144
View File
@@ -0,0 +1,144 @@
# hello-platform
Minimal macOS and iOS app that validates the platform foundation: a "Hello,
platform!" title, a count label and an Increment button. All state lives in
Dialect; SwiftUI only renders the view model and sends one input event.
## Layout
```text
hello/hello-platform/
├── dialect.yml Dialect v4 source: fields, oneliners, shoulds
├── util/
│ ├── build-mac generate → build → package
│ ├── run-mac run the packaged .app
│ ├── prepare-ios generate → xcodegen project
│ └── step/
│ ├── generateDialect sibling ../dialect generator on dialect.yml
│ ├── buildMac swift build in ver-mac/
│ ├── packageMac ver-mac/.build/hello-platform.app
│ ├── runMac launch Contents/MacOS/hello-platform
│ └── prepareIOS xcodegen in ver-ios/
├── ver-mac/
│ ├── Package.swift one executable target, path "src", macOS 13
│ ├── Info.plist org.opengamestudio.hello-platform, AppIcon
│ ├── res/AppIcon.icns copied into the bundle's Resources
│ ├── .build/ SPM output + packaged .app (git-ignored)
│ └── src/
│ ├── HPApp.swift @main WindowGroup → HPView
│ ├── HPAppDelegate.swift builds HPComponent + HPVM, logs, calls setup()
│ ├── dialect.swift generated by Dialect, never hand-edited
│ ├── hp/ relative symlinks into components/hp
│ │ ├── hp.swift
│ │ ├── hpVM.swift
│ │ └── view/HPView.swift → components/hp/mac/view/HPView.swift
│ └── other/other.swift relative symlink into components/other
└── ver-ios/
├── project.yml xcodegen: target hello-platform, iOS 15
├── Info.plist org.opengamestudio.hello-platform
├── Assets.xcassets/ AppIcon.appiconset/AppIcon.png → res/AppIcon.png
├── hello-platform.xcodeproj generated, git-ignored
├── .build/ xcodebuild DerivedData (git-ignored)
└── src/
├── HPApp.swift @main WindowGroup → HPView
├── HPAppDelegate.swift same HPComponent + HPVM + logging as macOS
├── dialect.swift symlink → ../../ver-mac/src/dialect.swift
├── hp/ same links as ver-mac, except view/HPView.swift
│ → components/hp/ios/view/HPView.swift
└── other/other.swift same symlink as the macOS tree
```
`components/` is the source of truth. The `src/hp` and `src/other` entries are
symlinks, so edit the real files under `components/` and keep the links intact.
Both platforms share one `dialect.swift` (the iOS one is a symlink to `ver-mac`),
one `HPView` body (the iOS `components/hp/ios/view/HPView.swift` links back to
the macOS view) and one `res/AppIcon.png`.
## Shared components
- `components/hp/hp.swift` — `HPComponent` owns `DialectController(HPContext)`,
registers the generated effects and shoulds, publishes `singleton` and exposes
`setup()` (`hpSet(F.didSetup, true)`).
- `components/hp/hpVM.swift` — `HPVM` is an `ObservableObject` with
`@Published countText` and a weak `shared` instance.
- `components/hp/mac/view/HPView.swift` — SwiftUI view observing `HPVM`; the
button dispatches `hpSet(F.didClickIncrement, true)`. It is platform-neutral,
so `components/hp/ios/view/HPView.swift` is a symlink back to it and both
`src/hp/view/HPView.swift` links resolve to the same file.
- `components/other/other.swift` — helpers, including
`otherSetupConsoleLogging(ctrl, "HP")`, which prints every processed field to
stderr as `ИГР HP k/v: '<field>'/'<value>'`.
## Startup flow
1. `HPAppDelegate` creates `HPComponent` (which sets `HPComponent.singleton`)
and then `HPVM` (which sets `HPVM.shared`).
2. The launch callback (`applicationDidFinishLaunching` on macOS,
`application(_:didFinishLaunchingWithOptions:)` on iOS) registers console
logging and calls `hp.setup()`; the macOS one also activates the app.
3. `setup()` queues `didSetup` in the controller.
4. The controller applies the changed field, runs every registered should in
order, and queues each new `recentField` a should returns. Finally it reports
the context to callbacks: logging plus the `countText` oneliner, which copies
`c.countText` into `HPVM.shared`.
5. `HPView` re-renders from the published view model.
## Dialect rules (`dialect.yml`)
Fields: `count`, `countText`, `didClickIncrement`, `didLaunch`, `didSetup`.
Shoulds exist for `count`, `countText` and `didLaunch`; `didClickIncrement` and
`didSetup` are pure inputs.
- `count`:
- on `didClickIncrement` when `count == 7` → `count += 10`;
- on every `didClickIncrement` → `count += 1`.
The first matching rule returns, so the click made while the count is 7 adds
10 and jumps to 17.
- `countText`:
- on `count` → `"Count: '<count>'"`;
- on `didLaunch` → `"Press the button to count"`.
- `didLaunch`: on `didSetup` while `didLaunch == false` → `true`, once.
Oneliners: `countText` → `HPVM.shared!.countText = c.countText`.
## Build and run
```sh
cd hello/hello-platform
util/build-mac
util/run-mac
```
`generateDialect` expects the sibling `../dialect` checkout (so
`/Volumes/MOE/p/dialect` for this workspace). `build-mac` runs the steps in
order: regenerate `ver-mac/src/dialect.swift`, `swift build`, then package
`ver-mac/.build/debug/hello-platform`, `Info.plist` and `res/` into
`ver-mac/.build/hello-platform.app`.
iOS needs `xcodegen` (see README prerequisites):
```sh
cd hello/hello-platform
util/prepare-ios
xcodebuild -project ver-ios/hello-platform.xcodeproj \
-scheme hello-platform -sdk iphonesimulator \
-destination 'generic/platform=iOS Simulator' \
CODE_SIGNING_ALLOWED=NO build
```
`prepare-ios` regenerates `dialect.swift` and then runs `xcodegen` in
`ver-ios/`. The generated `.xcodeproj` and `.build/` are git-ignored, so
re-run it after changing `project.yml` or `Info.plist`.
## Pitfalls
- Change `dialect.yml`, not `dialect.swift`; retyping or reformatting the
generated file is pointless because every build overwrites it.
- Every should label (`1. Upon ...`) must end with a colon: the sibling generator
drops its last character (`../dialect/components/yml/ymlFun.swift`).
- A should function may change only one field; its returned `recentField` drives
the next queue entry.
- The generated oneliner and `hpSet` force-unwrap `HPVM.shared` /
`HPComponent.singleton`; both must exist before dispatch.
- Only one `dialect.swift` exists: `ver-ios/src/dialect.swift` is a symlink to
the macOS file, so `prepare-ios` regenerates the same source.
+9
View File
@@ -0,0 +1,9 @@
#!/bin/bash -e
SDIR=$(cd "$(dirname "$0")" ; pwd -P)
T=$SDIR/step
TARGET=hello-platform
STEP=0
source $T/generateDialect $TARGET
source $T/prepareIOS $TARGET
+8
View File
@@ -0,0 +1,8 @@
#!/bin/bash -e
TARGET=$1
STEP=$((STEP+1))
echo -e "\n> > > > Step №$STEP. Generate Xcode project for '$TARGET' iOS"
cd $SDIR/../ver-ios
xcodegen
@@ -0,0 +1 @@
../../../../../../res/AppIcon.png
@@ -0,0 +1,14 @@
{
"images" : [
{
"filename" : "AppIcon.png",
"idiom" : "universal",
"platform" : "ios",
"size" : "1024x1024"
}
],
"info" : {
"author" : "xcode",
"version" : 1
}
}
+29
View File
@@ -0,0 +1,29 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>CFBundleName</key>
<string>hello-platform</string>
<key>CFBundleDisplayName</key>
<string>hello-platform</string>
<key>CFBundleIdentifier</key>
<string>org.opengamestudio.hello-platform</string>
<key>CFBundleExecutable</key>
<string>hello-platform</string>
<key>CFBundlePackageType</key>
<string>APPL</string>
<key>CFBundleShortVersionString</key>
<string>1.0</string>
<key>CFBundleVersion</key>
<string>1</string>
<key>UILaunchScreen</key>
<dict/>
<key>UISupportedInterfaceOrientations</key>
<array>
<string>UIInterfaceOrientationLandscapeLeft</string>
<string>UIInterfaceOrientationLandscapeRight</string>
<string>UIInterfaceOrientationPortrait</string>
<string>UIInterfaceOrientationPortraitUpsideDown</string>
</array>
</dict>
</plist>
+15
View File
@@ -0,0 +1,15 @@
name: hello-platform
options:
bundleIdPrefix: org.opengamestudio
targets:
hello-platform:
type: application
platform: iOS
deploymentTarget: "15.0"
sources:
- path: Assets.xcassets
- path: src
settings:
base:
INFOPLIST_FILE: Info.plist
PRODUCT_BUNDLE_IDENTIFIER: org.opengamestudio.hello-platform
@@ -0,0 +1,12 @@
import SwiftUI
@main
struct HPApp: App {
@UIApplicationDelegateAdaptor(HPAppDelegate.self) private var appDelegate
var body: some Scene {
WindowGroup {
HPView(appDelegate.hpVM)
}
}
}
@@ -0,0 +1,18 @@
import UIKit
final class HPAppDelegate:
NSObject,
UIApplicationDelegate
{
let hp = HPComponent()
let hpVM = HPVM()
func application(
_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
) -> Bool {
otherSetupConsoleLogging(hp.ctrl, "HP")
hp.setup()
return true
}
}
+1
View File
@@ -0,0 +1 @@
../../ver-mac/src/dialect.swift
+1
View File
@@ -0,0 +1 @@
../../../../../components/hp/hp.swift
+1
View File
@@ -0,0 +1 @@
../../../../../components/hp/hpVM.swift
@@ -0,0 +1 @@
../../../../../../components/hp/ios/view/HPView.swift
+1
View File
@@ -0,0 +1 @@
../../../../../components/other/other.swift
BIN
View File
Binary file not shown.

After

Width:  |  Height:  |  Size: 158 KiB