diff --git a/AGENTS.md b/AGENTS.md index 4c02aa8..863212d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,82 +3,58 @@ Native SwiftUI apps on the Dialect v4 declarative reactive engine (v2.0.0). Remote: `https://git.opengamestudio.org/mahjong/mahjong`. -## Status +## Apps -- `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. +- `hello/hello-platform/` — macOS + iOS platform-support sample (Hello counter). Its + structure, startup flow and dialect rules are in + [docs/hello-platform.md](docs/hello-platform.md); read that file whenever anything + from hello-platform is referenced. ## Layout -- `/dialect.yml` → `/ver-mac/src/dialect.swift` (Blue iOS links to it). +- `/dialect.yml` → generates `/ver-mac/src/dialect.swift`. - `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. +- `hello-platform` uses `components/hp/` for its component, view model and shared + SwiftUI view, and `components/other/` for shared helpers. - `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 -Prereqs: `brew install raylib xcodegen`; siblings `../dialect` (`util/build-generator`) -and `../raylib-ios-xcframeworks` (raylib + libEGL/libGLESv2; presence checked only). +Prereqs: sibling `../dialect` checkout (`util/build-generator`). ```sh -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 +cd hello/hello-platform +util/build-mac +util/run-mac +util/prepare-ios # xcodegen; xcodebuild command is in docs/hello-platform.md ``` -macOS scripts regenerate Dialect, `swift build`, then package `ver-mac/res/` into -`ver-mac/.build/.app`. iOS also checks XCFrameworks, stages ANGLE symlinks in -`ver-ios/.build/`, then runs XcodeGen (same scripts for `ogs-chkgfx`/`ogs-mahjong`). +`build-mac` regenerates Dialect, runs `swift build` in `ver-mac/`, then packages the +binary and `ver-mac/res/` into `ver-mac/.build/.app`. `ver-ios/` mirrors +`ver-mac/` and shares `dialect.swift`, `HPView` and the app icon via symlinks. 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 -- Edit `/dialect.yml` / `components/`, then `util/build--mac`; manual edits to - the generated `dialect.swift` are overwritten. +- Edit `/dialect.yml` / `components/`, then `util/build-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 = ""` hand-patched in ASCII order or `F.` 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. + `static let = ""` hand-patched in ASCII order or `F.` + will not build. +- Validate: `ruby -ryaml -e 'YAML.load_file("hello/hello-platform/dialect.yml")'`. + 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 -- 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`). +- Mirror Swift/iOS into Android (naming, text, layout, styling). +- Compose: named `MaterialTheme.typography` styles over `fontSize`. - 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. @@ -88,6 +64,5 @@ Dangling-symlink audit: 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 +fills, counts, non-repetitive explanations); never substitute working-tree code for a requested historical revision. diff --git a/README.md b/README.md index 000921c..9168c44 100644 --- a/README.md +++ b/README.md @@ -15,4 +15,4 @@ | 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 | √ | √ | | | | | diff --git a/components/hp/ios/view/HPView.swift b/components/hp/ios/view/HPView.swift new file mode 120000 index 0000000..6457e39 --- /dev/null +++ b/components/hp/ios/view/HPView.swift @@ -0,0 +1 @@ +../../../hp/mac/view/HPView.swift \ No newline at end of file diff --git a/docs/hello-platform.md b/docs/hello-platform.md new file mode 100644 index 0000000..ccd78aa --- /dev/null +++ b/docs/hello-platform.md @@ -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: ''/''`. + +## 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: ''"`; + - 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. diff --git a/hello/hello-platform/util/prepare-ios b/hello/hello-platform/util/prepare-ios new file mode 100755 index 0000000..a200ebd --- /dev/null +++ b/hello/hello-platform/util/prepare-ios @@ -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 diff --git a/hello/hello-platform/util/step/prepareIOS b/hello/hello-platform/util/step/prepareIOS new file mode 100755 index 0000000..d557711 --- /dev/null +++ b/hello/hello-platform/util/step/prepareIOS @@ -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 diff --git a/hello/hello-platform/ver-ios/Assets.xcassets/AppIcon.appiconset/AppIcon.png b/hello/hello-platform/ver-ios/Assets.xcassets/AppIcon.appiconset/AppIcon.png new file mode 120000 index 0000000..5b9224e --- /dev/null +++ b/hello/hello-platform/ver-ios/Assets.xcassets/AppIcon.appiconset/AppIcon.png @@ -0,0 +1 @@ +../../../../../../res/AppIcon.png \ No newline at end of file diff --git a/hello/hello-platform/ver-ios/Assets.xcassets/AppIcon.appiconset/Contents.json b/hello/hello-platform/ver-ios/Assets.xcassets/AppIcon.appiconset/Contents.json new file mode 100644 index 0000000..cefcc87 --- /dev/null +++ b/hello/hello-platform/ver-ios/Assets.xcassets/AppIcon.appiconset/Contents.json @@ -0,0 +1,14 @@ +{ + "images" : [ + { + "filename" : "AppIcon.png", + "idiom" : "universal", + "platform" : "ios", + "size" : "1024x1024" + } + ], + "info" : { + "author" : "xcode", + "version" : 1 + } +} diff --git a/hello/hello-platform/ver-ios/Info.plist b/hello/hello-platform/ver-ios/Info.plist new file mode 100644 index 0000000..4d57246 --- /dev/null +++ b/hello/hello-platform/ver-ios/Info.plist @@ -0,0 +1,29 @@ + + + + + CFBundleName + hello-platform + CFBundleDisplayName + hello-platform + CFBundleIdentifier + org.opengamestudio.hello-platform + CFBundleExecutable + hello-platform + CFBundlePackageType + APPL + CFBundleShortVersionString + 1.0 + CFBundleVersion + 1 + UILaunchScreen + + UISupportedInterfaceOrientations + + UIInterfaceOrientationLandscapeLeft + UIInterfaceOrientationLandscapeRight + UIInterfaceOrientationPortrait + UIInterfaceOrientationPortraitUpsideDown + + + diff --git a/hello/hello-platform/ver-ios/project.yml b/hello/hello-platform/ver-ios/project.yml new file mode 100644 index 0000000..cc5a06c --- /dev/null +++ b/hello/hello-platform/ver-ios/project.yml @@ -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 diff --git a/hello/hello-platform/ver-ios/src/HPApp.swift b/hello/hello-platform/ver-ios/src/HPApp.swift new file mode 100644 index 0000000..9287228 --- /dev/null +++ b/hello/hello-platform/ver-ios/src/HPApp.swift @@ -0,0 +1,12 @@ +import SwiftUI + +@main +struct HPApp: App { + @UIApplicationDelegateAdaptor(HPAppDelegate.self) private var appDelegate + + var body: some Scene { + WindowGroup { + HPView(appDelegate.hpVM) + } + } +} diff --git a/hello/hello-platform/ver-ios/src/HPAppDelegate.swift b/hello/hello-platform/ver-ios/src/HPAppDelegate.swift new file mode 100644 index 0000000..8822ff1 --- /dev/null +++ b/hello/hello-platform/ver-ios/src/HPAppDelegate.swift @@ -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 + } +} diff --git a/hello/hello-platform/ver-ios/src/dialect.swift b/hello/hello-platform/ver-ios/src/dialect.swift new file mode 120000 index 0000000..a931c95 --- /dev/null +++ b/hello/hello-platform/ver-ios/src/dialect.swift @@ -0,0 +1 @@ +../../ver-mac/src/dialect.swift \ No newline at end of file diff --git a/hello/hello-platform/ver-ios/src/hp/hp.swift b/hello/hello-platform/ver-ios/src/hp/hp.swift new file mode 120000 index 0000000..b83cde2 --- /dev/null +++ b/hello/hello-platform/ver-ios/src/hp/hp.swift @@ -0,0 +1 @@ +../../../../../components/hp/hp.swift \ No newline at end of file diff --git a/hello/hello-platform/ver-ios/src/hp/hpVM.swift b/hello/hello-platform/ver-ios/src/hp/hpVM.swift new file mode 120000 index 0000000..6997858 --- /dev/null +++ b/hello/hello-platform/ver-ios/src/hp/hpVM.swift @@ -0,0 +1 @@ +../../../../../components/hp/hpVM.swift \ No newline at end of file diff --git a/hello/hello-platform/ver-ios/src/hp/view/HPView.swift b/hello/hello-platform/ver-ios/src/hp/view/HPView.swift new file mode 120000 index 0000000..cf4cd2c --- /dev/null +++ b/hello/hello-platform/ver-ios/src/hp/view/HPView.swift @@ -0,0 +1 @@ +../../../../../../components/hp/ios/view/HPView.swift \ No newline at end of file diff --git a/hello/hello-platform/ver-ios/src/other/other.swift b/hello/hello-platform/ver-ios/src/other/other.swift new file mode 120000 index 0000000..8c61410 --- /dev/null +++ b/hello/hello-platform/ver-ios/src/other/other.swift @@ -0,0 +1 @@ +../../../../../components/other/other.swift \ No newline at end of file diff --git a/res/AppIcon.png b/res/AppIcon.png new file mode 100644 index 0000000..b91ad1c Binary files /dev/null and b/res/AppIcon.png differ