@scenoco-three/unity 1.4.0 → 1.6.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/dist/cli.js +8 -5
- package/dist/convert.d.ts +41 -0
- package/dist/convert.js +326 -38
- package/dist/export.d.ts +22 -3
- package/dist/export.js +243 -33
- package/dist/page.d.ts +2 -0
- package/dist/page.js +30 -12
- package/dist/stub.d.ts +7 -2
- package/dist/stub.js +66 -25
- package/dist/twin.d.ts +52 -0
- package/dist/twin.js +1076 -0
- package/package.json +2 -2
- package/unity/KeepAcrossScenes.cs +9 -2
- package/unity/PORTING.md +100 -52
- package/unity/SceNoCoImporter.cs +334 -883
- package/unity/SceNoCoValidate.cs +96 -0
- package/unity/SplineKnotNodes.cs +66 -0
- package/unity/SplineMesh.cs +255 -0
- package/unity/Driver/SceNoCo.Driver.asmdef +0 -32
- package/unity/Driver/SceNoCoDriver.cs +0 -697
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@scenoco-three/unity",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.6.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.
|
|
57
|
+
"@scenoco-three/core": "^1.6.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)
|
|
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
|
|
4
|
-
|
|
5
|
-
the
|
|
6
|
-
is the
|
|
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
|
|
11
|
-
|
|
12
|
-
|
|
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
|
-
- `
|
|
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 (
|
|
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**:
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
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.
|
|
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
|
|
124
|
-
`Instantiate()` where the code cloned
|
|
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
|
-
|
|
147
|
-
`window.__scenoco` (its `help()` says how); this one with
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
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`.
|