@scenoco-three/unity 1.3.1 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@scenoco-three/unity",
3
- "version": "1.3.1",
3
+ "version": "1.5.0",
4
4
  "description": "Export a SceNoCo game's prefabs, scenes, meshes and materials into a Unity project: nested prefabs, shared materials, behaviours as MonoBehaviours with their fields wired.",
5
5
  "keywords": [
6
6
  "three",
@@ -54,7 +54,7 @@
54
54
  "rolldown": "^1.0.3"
55
55
  },
56
56
  "peerDependencies": {
57
- "@scenoco-three/core": "^1.3.1",
57
+ "@scenoco-three/core": "^1.5.0",
58
58
  "vite": ">=6"
59
59
  }
60
60
  }
@@ -5,7 +5,8 @@ namespace SceNoCo
5
5
  {
6
6
  /// <summary>
7
7
  /// Keeps its object when a scene loads: the first scene's Input object — its EventSystem and UI input
8
- /// module — stays for the whole game, as the page's input does on the web.
8
+ /// module — stays for the whole game, as the page's input does on the web. Each scene with a page has
9
+ /// one, so it plays on its own too; the one already kept wins.
9
10
  /// </summary>
10
11
  [DisallowMultipleComponent]
11
12
  public sealed class KeepAcrossScenes : MonoBehaviour
@@ -18,7 +19,13 @@ namespace SceNoCo
18
19
  #else
19
20
  foreach (var other in FindObjectsByType<KeepAcrossScenes>(FindObjectsSortMode.None))
20
21
  #endif
21
- if (other != this && other.name == name) { Destroy(gameObject); return; }
22
+ if (other != this && other.name == name)
23
+ {
24
+ // Off at once, so its EventSystem is never a second one, even for the rest of this frame.
25
+ gameObject.SetActive(false);
26
+ Destroy(gameObject);
27
+ return;
28
+ }
22
29
  DontDestroyOnLoad(gameObject);
23
30
  }
24
31
  }
package/unity/PORTING.md CHANGED
@@ -1,15 +1,22 @@
1
1
  # Porting a SceNoCo game to this Unity project
2
2
 
3
- `scenoco-unity` wrote the game here as Unity's own assets — prefabs, scenes, meshes, materials,
4
- particle systems, the page as UXML and USS, the input actions, the project's rendering settings — and
5
- the game's code as C# stubs holding its TypeScript. What is left is the code, file by file. This card
6
- is the rules for that. It is rewritten by every export.
3
+ `scenoco-unity` wrote the game here: its scenes and prefabs as Scenoco's text, which Unity builds
4
+ into `.unity` and `.prefab` assets; the meshes, materials, particle systems and post effects they use;
5
+ the page as UXML and USS; the input actions; the project's rendering settings — and the game's code as
6
+ C# stubs holding its TypeScript. What is left is the code, file by file. This card is the rules for
7
+ that; Diceload's `unity-game` skill (in `.claude/skills/`) is how you work in this project. It is
8
+ rewritten by every export.
7
9
 
8
10
  ## What is here
9
11
 
10
- - `Assets/Prefabs`, `Assets/Scenes`, `Assets/Meshes`, `Assets/Materials`, `Assets/Textures`: built by
11
- `unity command scenoco.import` (or **SceNoCo ▸ Import**), which lists what did not come across.
12
- Read every warning it prints.
12
+ - `Assets/Prefabs/*.uprefab`, `Assets/Scenes/*.uscene`: the prefabs and scenes as text, each beside
13
+ the asset Scenoco (`com.roro.scenoco`) builds from it. Read its `AGENTS.md` before changing one:
14
+ it is how a scene is written, and what to do with an error at a line. A scene's fog and ambient
15
+ light are on the scene, not in its text.
16
+ - `Assets/Meshes`, `Assets/Materials`, `Assets/Textures`, `Assets/Terrains`: what the text names, made
17
+ by the importer (**SceNoCo ▸ Import**, or by itself after an export compiles). Its Console lines
18
+ list what did not come across, and each text twin that Scenoco could not build, with its line.
19
+ Read every warning.
13
20
  - `Assets/Scripts/<Behaviour>.cs`: one stub per behaviour. Its wired fields are real C# fields, and the
14
21
  prefabs already set them; keep their names. Every other field, and every method, holds its
15
22
  TypeScript as comments; so does the code its file holds outside the class. Write the C# in its
@@ -19,8 +26,12 @@ is the rules for that. It is rewritten by every export.
19
26
  `main.ts` — as its TypeScript in comments. Decide what each becomes (below).
20
27
  - `Assets/UI`: the page — one `.uxml` per `UIDocument`, one per `<template>`, `Page.uss`, its images
21
28
  and its fonts. Rewritten by every export: change the page, not these.
29
+ - `Assets/Models`, `Assets/Audio`: the game's model and sound files. A placed model (`<Goblin />`) is
30
+ a placed `.glb`, turned 180° about y for glTFast's mirror; a model code instantiates needs the same
31
+ turn: `Instantiate(model, position, rotation * Quaternion.Euler(0, 180, 0))`. A model with settings
32
+ (`sharedModel(url, { castShadow: false })`) is its variant, `Assets/Models/<name>.prefab`.
22
33
  - `Assets/SceNoCo/Input/SceNoCo.inputactions`: the project-wide input actions.
23
- - `Assets/SceNoCo/Driver`: the `scenoco` commands that drive the game in Play mode (below).
34
+ - `Packages/manifest.json` has Scenoco and Diceload, which the export added.
24
35
 
25
36
  ## Code
26
37
 
@@ -30,7 +41,9 @@ is the rules for that. It is rewritten by every export.
30
41
  - **The world is mirrored on Z.** three.js is right-handed, Unity left-handed; the export negates z.
31
42
  Negate z in every vector literal and every z the code computes; a rotation about x or y turns the
32
43
  other way. `lookAt`, forward vectors and cameras need the same care. The prefabs are already
33
- mirrored: only code is left.
44
+ mirrored: only code is left. A `Vector3` field a rotation is set from — degrees a second about each
45
+ axis, a spin — came across mirrored as a rotation: x and y negated, z kept, so
46
+ `transform.Rotate(speed * Time.deltaTime)` needs nothing more.
34
47
  - **A node's `position`, `rotation` and `scale` are local**: `transform.localPosition`,
35
48
  `localRotation`, `localScale`. `getWorldPosition` is `transform.position`. `eulerAngles` are degrees
36
49
  on both sides; three's `rotation` is radians.
@@ -39,7 +52,7 @@ is the rules for that. It is rewritten by every export.
39
52
  instantiates is a `GameObject` field set to its prefab asset. `findObjectOfType` is
40
53
  `FindFirstObjectByType`, `findObjectsOfType` is `FindObjectsByType<T>()` (before Unity 6.6,
41
54
  `FindObjectsByType<T>(FindObjectsSortMode.None)`).
42
- - **Tweens map to DOTween's calls**, once the project has DOTween (Asset Store, free; not part of this export):
55
+ - **Tweens map to DOTween's calls**, once the project has the free DOTween (below, "Tweens"):
43
56
  `node.doMove(to, 0.5).setEase(Ease.OutBack)` is `transform.DOMove(to, 0.5f).SetEase(Ease.OutBack)`,
44
57
  `Tween.sequence().append(a).join(b)` is `DOTween.Sequence().Append(a).Join(b)`,
45
58
  `Tween.delayedCall(s, fn)` is `DOVirtual.DelayedCall(s, fn, false)`, `Tween.float` is `DOVirtual.Float`,
@@ -49,6 +62,10 @@ is the rules for that. It is rewritten by every export.
49
62
  given as a `Vector3` is degrees in both; an `Euler` was radians, so convert it.
50
63
  - **Coroutines**: a `*generator` is an `IEnumerator`, `this.startCoroutine(this.x())` is
51
64
  `StartCoroutine(X())`, `yield new WaitForSeconds(s)` is the same, `yield null` waits a frame.
65
+ - **A scene's own behaviours** — written on its `<Scene>` — are on one object that holds the whole
66
+ scene, as three's `Scene` does. `dontDestroyOnLoad(this)` there is `DontDestroyOnLoad(gameObject)`
67
+ and keeps the scene, as it did. Unity keeps only a root object: on a child, it is
68
+ `DontDestroyOnLoad(transform.root.gameObject)` — what SceNoCo kept, the topmost node.
52
69
  - **Events**: an `Event<T>` field is a C# `event Action<T>`; `listen(e, f)` is `e += f`, and its
53
70
  removal belongs in `OnDestroy`.
54
71
  - **Colours are `Color`**, as SceNoCo's are three's `Color`: a field the scenes wire comes across
@@ -57,24 +74,29 @@ is the rules for that. It is rewritten by every export.
57
74
  `_EmissionColor` and `_Metallic`, and `node.material` is `GetComponent<Renderer>().material` — a
58
75
  copy of its own, as a three material written in an element is. URP has no emissive intensity: the
59
76
  importer wrote `_EmissionColor` as the colour's linear value times it. Code that animates a glow
60
- keeps the colour, as the TSX wrote it, and sets `(color.linear * intensity).gamma`.
77
+ keeps the colour, as the TSX wrote it, and sets `(color.linear * intensity).gamma`. When the game's
78
+ code sets an emissive, every lit material has emission on — black where the TSX gave none — so a
79
+ colour set at runtime glows; without the `_EMISSION` keyword, URP draws none.
61
80
  - **Physics layers** came across: SceNoCo's layer n is Unity's user layer n + 7, named after the
62
81
  game's own constant (`Layer.ball`), set on the objects, and the pairs `ignoreLayerCollision` set are
63
82
  in the project's Physics settings. Code that names a layer adds 7.
64
83
  - **Numbers**: `number` is `float`, or `int` where it counts. Keep the units: SceNoCo's are Unity's.
65
84
  A union field the scenes wire stays as its stub types it — `string`, `float` — so the prefabs keep
66
- their values. **Never change a wired field's type**: Unity drops a value it cannot read, and the
67
- next scene saved loses it for good. If one must change, run `unity command scenoco.import` before
68
- saving anything.
69
- - **Particle systems** came across as Unity's own, module by module: `play()`, `stop()` and
70
- `isPlaying` are the same.
71
- - **Terrains** came across as Unity's `TerrainData` assets, with the `Terrain` and `TerrainCollider`
72
- on a child named Terrain at the data's corner: SceNoCo's terrain is centred on its node with heights
73
- in metres, Unity's starts at its object with heights 0..1 of `size.y`. A layer is its colour; a
74
- layer's texture is set in Unity. In code, `terrain.sampleHeight(p)` is `Terrain.SampleHeight(p)`;
75
- `data.heightAt(x, z)` (metres from the centre) is `terrain.SampleHeight` at that point under the
76
- node, and `steepnessAt` is `terrainData.GetSteepness` at its 0..1 position. The game's own height
77
- function, if it has one, ports as it is.
85
+ their values. **Never change a wired field's type**: the scene's text would no longer read, and
86
+ Scenoco says so at its line. If one must change, change the value in the text to match.
87
+ - **`onValidate` is `OnValidate`**, with nothing added: `Assets/Editor/SceNoCoValidate.cs` also calls
88
+ it when the editor moves the object, or one a field holds, as SceNoCo does. Unity also calls it on
89
+ load, on prefab assets and while several scenes are open: return unless `gameObject.scene.isLoaded`,
90
+ find what it places by in that scene (its roots), and leave a value within a few mm as it is, or
91
+ every load marks the scene changed. Creating or destroying objects there waits for `EditorApplication.delayCall`.
92
+ - **A missing component is a fake null**: `GetComponent<T>() ?? AddComponent<T>()` and `?.` never
93
+ see it. Use `TryGetComponent`, or `== null`.
94
+ - **Particle systems** are Unity's own, module by module: `play()`, `stop()`, `isPlaying` are the same.
95
+ - **Terrains** are `TerrainData` assets on a child named Terrain at the data's corner: SceNoCo's is
96
+ centred, heights in metres; Unity's starts at its object, heights 0..1 of `size.y`. `sampleHeight(p)`
97
+ is `Terrain.SampleHeight(p)`, `data.heightAt(x, z)` is `SampleHeight` at that point under the node,
98
+ `steepnessAt` is `terrainData.GetSteepness` at its 0..1 position. Unity's Terrain never rotates (it ignores
99
+ its object's rotation): a terrain the game tilts is, in the port, its heights as a mesh with a MeshCollider.
78
100
 
79
101
  ## Input
80
102
 
@@ -91,13 +113,35 @@ no class of your own between the game and them:
91
113
  | `Input.getMouseButtonDown(MouseButton.Left)` | `Pointer.current.press.wasPressedThisFrame` — a finger too |
92
114
  | `Input.mousePosition`, `Input.pointer` | `Pointer.current.position.ReadValue()` (pixels, from the bottom-left) |
93
115
  | `Input.mouseDelta` | `Pointer.current.delta.ReadValue()` |
94
- | `Input.getButtonDown('Continue')` from a `data-button` | the element's click: `root.Q("banner").RegisterCallback<ClickEvent>(…)` |
116
+ | `Input.getButtonDown('Continue')` from a `data-button` | the element's click: every element of the page with `data-button="Continue"` has the class `button-Continue` — `root.Query(className: "button-Continue").ForEach(b => b.RegisterCallback<ClickEvent>(…))` |
95
117
 
96
118
  `getAxis` eases toward the keys in SceNoCo and Unity's legacy Input; an action does not. Where the
97
119
  easing matters, ease the value in the behaviour (`Mathf.MoveTowards` at the axis' sensitivity, 3/s).
98
120
  The first scene has an `Input` object — the UI's EventSystem with its Input System module — kept for
99
121
  the whole game: UI clicks need it.
100
122
 
123
+ ## Tweens: DOTween, the free one
124
+
125
+ SceNoCo's tweens are DOTween's API, and the free DOTween has all of it: every `do…` shortcut core has
126
+ (`DOMove`, `DOLocalRotate`, `DOJump`, `DOPunch…`, `DOShake…`, `DOLookAt`, Camera `DOFieldOfView` and
127
+ `DOOrthoSize`, Light `DOColor` and `DOIntensity`, Material `DOColor`, `DOFade` and `DOFloat`), sequences,
128
+ `DOTween.To`, `DOVirtual`, every setting (`SetEase`, `SetLoops`, `SetDelay`, `SetRelative`, `SetUpdate`,
129
+ `SetLink`, `From`), callback and control. DOTween Pro adds what SceNoCo has no counterpart for — visual
130
+ Animation and Path components, `DOSpiral`, TextMesh Pro and 2D Toolkit shortcuts — so a port never
131
+ needs it. The export does not install DOTween; it says when the game uses tweens.
132
+
133
+ Install it with the person, from Demigiant only: the [Asset Store](https://assetstore.unity.com/packages/tools/animation/dotween-hotween-v2-27676)
134
+ (their account: **Package Manager ▸ My Assets ▸ DOTween ▸ Import**), or the zip from
135
+ [dotween.demigiant.com/download](https://dotween.demigiant.com/download) into `Assets/Plugins/` — ask
136
+ before downloading. Then **Tools ▸ Demigiant ▸ DOTween Utility Panel ▸ Setup DOTween… ▸ Apply** (again
137
+ after every update); for game code in an `.asmdef`, **Create ASMDEF…** there and reference `DOTween.Modules`.
138
+
139
+ Where a port differs from the TypeScript:
140
+ - A colour other than a material's main one is named: `material.DOColor(to, "_EmissionColor", d)`;
141
+ `DOFloat(to, "_Metallic", d)`. URP has no emissive intensity to tween: tween `_EmissionColor` (Materials, above).
142
+ - `setUpdate(true)` tweens run on unscaled time, which a Diceload simulation plays with
143
+ `PlayInRealTime`; every other tween runs on the held game clock.
144
+
101
145
  ## Code outside behaviours
102
146
 
103
147
  `Assets/Scripts/Modules` holds the rest, as TypeScript, for you to decide:
@@ -115,19 +159,31 @@ the whole game: UI clicks need it.
115
159
 
116
160
  The page came across as it is, rule by rule. What code does with it:
117
161
 
118
- - `getElementById` (or the page's `$`) is `root.Q("id")` on `GetComponent<UIDocument>().rootVisualElement`,
162
+ - `getElementById` (or the page's `$`) is `root.Q("id")` on `GetComponent<UIDocument>().rootVisualElement`
163
+ (an object takes one UIDocument: several on one node are on children named after their elements),
119
164
  found once in `Awake` or `OnEnable`; `textContent` is `Label.text` (an element code fills is a
120
165
  `Label`); `classList.add`, `remove`, `toggle` are `AddToClassList`, `RemoveFromClassList`,
121
166
  `EnableInClassList`; `transitionend` is `TransitionEndEvent`; `style.left = '30%'` is
122
167
  `style.left = Length.Percent(30)`.
123
- - A `<template>` is `Assets/UI/<id>.uxml`: give the behaviour a `VisualTreeAsset` field set to it, and
124
- `Instantiate()` where the code cloned it.
168
+ - A `<template>` is `Assets/UI/<id>.uxml`. A behaviour that took one by id (`this.chip = $('chip')`)
169
+ has a `VisualTreeAsset` field of that name, wired to it: `chip.Instantiate()` where the code cloned
170
+ it. Any other gets a field of its own, set in its scene.
125
171
  - The export says in its warnings what USS has no way to write. Change the page so it ports, and
126
172
  export again: the UI is never hand-edited here.
127
173
 
174
+ ## Sound
175
+
176
+ - Each scene's main camera has an `AudioListener`, as a new Unity scene's does: the page needs none,
177
+ and Unity plays nothing without one. One listener at a time: a camera added in code has none.
178
+ - `AudioContext` nodes are an `AudioSource` and its mixer. Sound the game makes as it plays — an
179
+ `AudioWorklet`, a synth — is `OnAudioFilterRead` on a GameObject of its own with an `AudioSource`
180
+ and no clip: it filters whatever source or listener shares its object, so never the camera's. It
181
+ runs on the audio thread; the game talks to it through a queue (`ConcurrentQueue`), as a worklet's
182
+ port does.
183
+
128
184
  ## Look
129
185
 
130
- The project's settings are the export's, for a three.js game: Linear colour space, HDR, no MSAA (as
186
+ The project's settings are the export's, set by the first import only (a port keeps its own changes), for a three.js game: Linear colour space, HDR, no MSAA (as
131
187
  SceNoCo renders), Forward+ (no light limit per object, as three has none), soft shadows, and no
132
188
  skybox reflections in a scene with no environment. Lights divide by π; fog and ambient light come from
133
189
  the scene. Cameras draw with no post-processing, as three's default renderer does. What `main.ts` set
@@ -143,27 +199,19 @@ up in code is the port's:
143
199
 
144
200
  ## Checking the port
145
201
 
146
- Drive both games through the same scenario and compare. The web game is driven with
147
- `window.__scenoco` (its `help()` says how); this one with the `scenoco` commands, which take the same
148
- verbs. They need Unity's CLI and its Pipeline package (`unity pipeline install`).
149
-
150
- ```bash
151
- unity command scenoco.help
152
- unity command scenoco.import
153
- unity command scenoco.setup --width 1080 --height 1920 # the web game's window size
154
- unity command scenoco.play
155
- unity command scenoco.ready # Play mode restarts the command server: repeat until it answers
156
- unity command scenoco.pause
157
- unity command scenoco.press --key Space
158
- unity command scenoco.until --target Game.phase --equals playing
159
- unity command scenoco.read --target Player
160
- unity command capture.game_view -- --save_path Screenshots/after-start.png
161
- ```
162
-
163
- Step the same number of frames on both sides and the two should read the same values: 1/60 s a
164
- frame on both clocks, the same fixed step (0.02 s) for physics. Compare values — `read --target
165
- Ball.transform.position` here, `__scenoco.eval(...)` there — rather than screenshots: they agree
166
- within a physics step. When a reading differs, the C# is wrong, not the scene: the scene came across
167
- by the exporter. UI timed with `WaitForSecondsRealtime`, and UI Toolkit's transitions, run on real
168
- time on both sides, so they do not line up frame for frame. A wait longer than the CLI's 30 s takes
169
- `--timeout 120` after the verb.
202
+ Play both games through the same scenario and compare. The web game is driven with
203
+ `window.__scenoco` (its `help()` says how); this one with a Diceload simulation — a PlayMode test
204
+ that loads a scene, presses keys on a held 1/60 s clock, reads the game's state in C# and takes
205
+ screenshots. The skill says how to write one and run it (`Tools~/unity-test`).
206
+
207
+ - **One simulation per phase** of the web game's: start, play, win or lose, restart. Step the same
208
+ number of frames on both sides and the two should read the same values: 1/60 s a frame on both
209
+ clocks, the same fixed step (0.02 s) for physics. Log what you compare (`Debug.Log`), and compare
210
+ values rather than screenshots — positions agree within a physics step.
211
+ - **Mirror the scenario's input**: a key pressed in frame N on the web is `Press` in frame N here.
212
+ Positions read here have z negated (the mirror above).
213
+ - **When a reading differs, the C# is wrong, not the scene**: the scene came across by the exporter.
214
+ When the scene is wrong, fix the game and export again rather than the text. A twin edited here
215
+ since the last export is kept, and the importer's warning names the new export to merge by hand.
216
+ - Unscaled time, screen size and sound in a simulation: the skill's `PlayInRealTime`, `SetResolution`
217
+ and `AudioLevel`.