some
This commit is contained in:
1 parent
66bd192621
commit
81ed1d9201
2 files changed
+92
-24
No files matched your search
@@ -12,9 +12,9 @@ and talk to the engine through generated functions like `rootSet(...)`.
|
||||
|
||||
Remote: `https://git.opengamestudio.org/mahjong/mahjong` · Version: `2.0.0`
|
||||
|
||||
> Current `dialect.yml` is still the "Root / counter" template inherited from the
|
||||
> dialect example — the Mahjong game logic has not been written yet. The app
|
||||
> shell, packaging and symlink wiring are in place.
|
||||
> `dialect.yml` is still the "Root / counter" template with a `Render` context
|
||||
> bolted on: the Mahjong game logic has not been written yet. The app shell,
|
||||
> packaging, symlink wiring and the raylib renderer are in place.
|
||||
|
||||
## Structure
|
||||
|
||||
@@ -28,28 +28,47 @@ components/ SHARED source-of-truth for all components.
|
||||
root/root.swift RootComponent (owns DialectController, registers
|
||||
effects + shoulds, sets didSetup on setup())
|
||||
root/rootVM.swift RootVM (ObservableObject / @Published countText)
|
||||
root/mac/view/RootView.swift Per-platform SwiftUI view
|
||||
root/mac/view/RootView.swift SwiftUI view: RenderView in a ZStack + UI
|
||||
render/render.swift RenderComponent (controller, effects + shoulds)
|
||||
render/renderVM.swift RenderVM (weak shared; glView, didPrepareGL,
|
||||
pixelSize, startTime, timer)
|
||||
render/renderConst.swift RENDER_CONFIG (sr_config), RENDER_FPS,
|
||||
RENDER_MODEL_CUBE, RENDER_OPENGL_ATTRS
|
||||
render/renderConstShader.swift RENDER_SHADER_* GLSL sources (GLSL 150)
|
||||
render/renderAux.swift renderDraw(vm), renderPixelSize(view)
|
||||
render/renderEffect.swift renderInit, renderLoadCubeModel,
|
||||
renderStartTimer, renderDeinit
|
||||
render/mac/view/RenderGLView.swift Thin NSOpenGLView: pixel format, callbacks
|
||||
-> renderSet(...), draw -> renderDraw
|
||||
render/mac/view/RenderView.swift NSViewRepresentable wrapper
|
||||
|
||||
game/ver-mac/ macOS app (SPM executable target "ogs-mahjong")
|
||||
Package.swift SPM manifest (macOS 13+, swift-tools 5.9); SPM C target
|
||||
"RaylibBridge" (bridge/) + links Homebrew raylib
|
||||
Package.swift SPM manifest (macOS 13+, swift-tools 5.9); C target
|
||||
"RaylibBridge" (bridge/) + links Homebrew raylib; the
|
||||
Swift target gets -Xcc -DGL_SILENCE_DEPRECATION
|
||||
Info.plist Bundle id org.opengamestudio.Mahjong, exec ogs-mahjong
|
||||
Resources/AppIcon.icns App icon
|
||||
Resources/assets/ Bundled glTF assets: cube.gltf (static),
|
||||
cube_texture.png
|
||||
bridge/ C target "RaylibBridge": raylib_bridge.{c,h}. Renders a
|
||||
rlgl scene (no raylib window) into an NSOpenGLView.
|
||||
cube_texture.png, cube_normal.png
|
||||
bridge/ C target "RaylibBridge": raylib_bridge.{c,h} with the
|
||||
public header in include/. Renders an rlgl scene (no
|
||||
raylib window) into the NSOpenGLView.
|
||||
src/
|
||||
GameApp.swift @main SwiftUI App entry
|
||||
AppDelegate.swift Creates RootComponent + RootVM, calls root.setup()
|
||||
AppDelegate.swift Creates Render/Root components + VMs, calls setup()
|
||||
dialect.swift GENERATED — do not hand-edit (see chicken-egg below)
|
||||
other/other.swift -> symlink components/other/other.swift
|
||||
render/renderConstShader.swift -> symlink components/render/renderConstShader.swift
|
||||
render/view/RenderGLView.swift -> symlink components/render/mac/view/RenderGLView.swift
|
||||
render/view/RenderView.swift -> symlink components/render/mac/view/RenderView.swift
|
||||
root/root.swift -> symlink components/root/root.swift
|
||||
root/rootVM.swift -> symlink components/root/rootVM.swift
|
||||
root/view/RootView.swift-> symlink components/root/mac/view/RootView.swift
|
||||
other/other.swift -> symlink components/other/other.swift
|
||||
render/render.swift -> symlink components/render/render.swift
|
||||
render/renderAux.swift -> symlink components/render/renderAux.swift
|
||||
render/renderConst.swift -> symlink components/render/renderConst.swift
|
||||
render/renderConstShader.swift -> symlink .../renderConstShader.swift
|
||||
render/renderEffect.swift -> symlink components/render/renderEffect.swift
|
||||
render/renderVM.swift -> symlink components/render/renderVM.swift
|
||||
render/view/RenderGLView.swift -> symlink components/render/mac/view/...
|
||||
render/view/RenderView.swift -> symlink components/render/mac/view/...
|
||||
root/root.swift -> symlink components/root/root.swift
|
||||
root/rootVM.swift -> symlink components/root/rootVM.swift
|
||||
root/view/RootView.swift -> symlink components/root/mac/view/...
|
||||
|
||||
ref/swiftraylib Symlink to ../../swiftraylib — the raylib/SwiftUI
|
||||
renderer sample the game will use for 3D rendering.
|
||||
@@ -73,7 +92,12 @@ directories whose files are **relative symlinks** back into `components/`:
|
||||
|
||||
```
|
||||
src/other/other.swift -> ../../../../components/other/other.swift (4 up)
|
||||
src/render/render.swift -> ../../../../components/render/render.swift (4 up)
|
||||
src/render/renderAux.swift -> ../../../../components/render/renderAux.swift (4 up)
|
||||
src/render/renderConst.swift-> ../../../../components/render/renderConst.swift (4 up)
|
||||
src/render/renderConstShader.swift -> ../../../../components/render/renderConstShader.swift (4 up)
|
||||
src/render/renderEffect.swift -> ../../../../components/render/renderEffect.swift (4 up)
|
||||
src/render/renderVM.swift -> ../../../../components/render/renderVM.swift (4 up)
|
||||
src/root/root.swift -> ../../../../components/root/root.swift (4 up)
|
||||
src/root/rootVM.swift -> ../../../../components/root/rootVM.swift (4 up)
|
||||
src/root/view/RootView.swift-> ../../../../../components/root/mac/view/RootView.swift (5 up)
|
||||
@@ -114,11 +138,48 @@ The 3D scene links against Homebrew **raylib** (`brew install raylib`). The
|
||||
The bridge renders with raylib's rlgl layer into an `NSOpenGLView` — raylib never
|
||||
creates its own window. `RootView` puts `RenderView` (backed by `RenderGLView`)
|
||||
behind the SwiftUI UI in a `ZStack`. A textured cube is drawn from `Resources/assets` (`cube.gltf` +
|
||||
`cube_texture.png`); the app rotates it each frame via `sr_set_rotation`.
|
||||
`cube_texture.png` + `cube_normal.png`); the app rotates it each frame via `sr_set_rotation`.
|
||||
(raylib's `LoadModelAnimations` only handles *skinned* meshes, so a plain
|
||||
node-rotation glTF animation cannot be played by the renderer — hence the cube is
|
||||
app-driven.) `packageMac` bundles `Resources/assets/` into the app.
|
||||
|
||||
Shaders and render constants live in **Swift**, not in C: GLSL sources are
|
||||
`RENDER_SHADER_*` in `components/render/renderConstShader.swift`, and
|
||||
`RENDER_CONFIG` / `sr_config` tunables are in `renderConst.swift`. `sr_init`
|
||||
compiles the shaders in place (no storage/`strdup`). `cube_normal.png` drives
|
||||
tangentless normal mapping via the derivative-based `cotangentFrame`. The
|
||||
context is OpenGL 3.2 Core (`RENDER_OPENGL_ATTRS`); on Apple Silicon the driver
|
||||
still reports 4.1/GLSL 4.10.
|
||||
|
||||
## Render architecture
|
||||
|
||||
The `Render` dialect context owns the GL scene. `RenderGLView` is a thin
|
||||
`NSOpenGLView`; it only translates AppKit callbacks into dialect fields, and the
|
||||
`render*` files do the actual work.
|
||||
|
||||
1. `AppDelegate` creates `RenderComponent` + `RenderVM` and calls
|
||||
`render.setup()` -> `didSetup` -> `didLaunch` (should) -> `pixelSize = [1, 1]`.
|
||||
2. SwiftUI builds `RenderView` -> `RenderGLView`; `prepareOpenGL()` sets
|
||||
`F.didPrepareGL`. Its oneliners run `renderInit` (`sr_init`), set
|
||||
`RenderVM.didPrepareGL = true`, and `renderStartTimer`.
|
||||
3. `reshape()` / `viewDidChangeBackingProperties()` compute the backing pixel
|
||||
size via `renderPixelSize` and set `F.reshapePixelSize` /
|
||||
`F.backingPixelSize`. The `pixelSize` shoulds fold these into `F.pixelSize`,
|
||||
whose oneliner stores `RenderVM.pixelSize`.
|
||||
4. The timer only sets `needsDisplay` every `1 / RENDER_FPS`. `draw(_:)` forwards
|
||||
to `renderDraw` (make context current, `sr_resize`, `sr_set_rotation`,
|
||||
`sr_render`, `flushBuffer`).
|
||||
5. A button click runs `rootSet(F.didClickIncrement)` -> RootComponent oneliner
|
||||
`renderSet(F.didClickIncrement)` -> `renderLoadCubeModel` (the cube is loaded
|
||||
on demand, not at startup).
|
||||
6. `RenderGLView.deinit` sets `F.willDeinit` -> `renderDeinit` (stop timer,
|
||||
`sr_shutdown`).
|
||||
|
||||
**GL context rule**: every raylib call must run with the view's context current.
|
||||
`renderInit`, `renderLoadCubeModel`, `renderDeinit` and `renderDraw` all call
|
||||
`openGLContext?.makeCurrentContext()` first. Loading a model/texture without it
|
||||
fails silently with `WARNING: TEXTURE: Failed to load texture`.
|
||||
|
||||
## Build & Run
|
||||
|
||||
```bash
|
||||
@@ -161,8 +222,10 @@ 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/`, and the `RootVM.shared!.countText = ...` oneliner in the
|
||||
generated `dialect.swift`). Do not flip it on without addressing those.
|
||||
`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
|
||||
|
||||
@@ -171,8 +234,11 @@ generated `dialect.swift`). Do not flip it on without addressing those.
|
||||
- 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`) and are accessed from the
|
||||
generated oneliners with force-unwrap (`RootVM.shared!.countText = ...`).
|
||||
(`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 / `sr_*` without making the view's GL context current first
|
||||
(see the GL context rule above).
|
||||
|
||||
## Skill: source-file study documents
|
||||
|
||||
@@ -184,5 +250,7 @@ fix) — follow the skill in `docs/file-summary.md`.
|
||||
- Write the result to `docs/<FileName>.html` (e.g. `docs/RaylibGLView.html`) and
|
||||
name the file's Git revision in the header. The file is the source of truth —
|
||||
document the exact revision requested, not the working tree.
|
||||
- Existing example: `docs/RaylibGLView.html` (single-cube `RaylibGLView.swift`).
|
||||
- Existing example: `docs/RaylibGLView.html` — documents the historical
|
||||
single-cube `RaylibGLView.swift`, since split into `RenderGLView.swift` plus
|
||||
the `render*` files.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
// swift-tools-version: 5.9
|
||||
import PackageDescription
|
||||
import Foundation
|
||||
import PackageDescription
|
||||
|
||||
let raylibPrefix = ProcessInfo.processInfo.environment["RAYLIB_PREFIX"] ?? "/opt/homebrew"
|
||||
|
||||
|
||||
Reference in new issue
Block a user