@scenoco-three/unity 0.9.9 → 1.1.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.
@@ -0,0 +1,25 @@
1
+ // Written by scenoco-unity on every export — edits here are overwritten.
2
+ using UnityEngine;
3
+
4
+ namespace SceNoCo
5
+ {
6
+ /// <summary>
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.
9
+ /// </summary>
10
+ [DisallowMultipleComponent]
11
+ public sealed class KeepAcrossScenes : MonoBehaviour
12
+ {
13
+ void Awake()
14
+ {
15
+ // One of a kind: a scene played on its own may hold another.
16
+ #if UNITY_6000_6_OR_NEWER
17
+ foreach (var other in FindObjectsByType<KeepAcrossScenes>())
18
+ #else
19
+ foreach (var other in FindObjectsByType<KeepAcrossScenes>(FindObjectsSortMode.None))
20
+ #endif
21
+ if (other != this && other.name == name) { Destroy(gameObject); return; }
22
+ DontDestroyOnLoad(gameObject);
23
+ }
24
+ }
25
+ }
@@ -0,0 +1,162 @@
1
+ # Porting a SceNoCo game to this Unity project
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.
7
+
8
+ ## What is here
9
+
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.
13
+ - `Assets/Scripts/<Behaviour>.cs`: one stub per behaviour. Its wired fields are real C# fields, and the
14
+ prefabs already set them; keep their names. Every other field, and every method, holds its
15
+ TypeScript as comments; so does the code its file holds outside the class. Write the C# in its
16
+ place and delete the comment. A stub compiles as it is, so port one at a time and keep the project
17
+ compiling. Stubs are written once and never overwritten.
18
+ - `Assets/Scripts/Modules/*.cs`: every other module of the game — helpers, tables, the entry
19
+ `main.ts` — as its TypeScript in comments. Decide what each becomes (below).
20
+ - `Assets/UI`: the page — one `.uxml` per `UIDocument`, one per `<template>`, `Page.uss`, its images
21
+ and its fonts. Rewritten by every export: change the page, not these.
22
+ - `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).
24
+
25
+ ## Code
26
+
27
+ - **Hooks are Unity's messages.** `awake` is `Awake`, `update` is `Update`, `onTriggerEnter` is
28
+ `OnTriggerEnter`; the stub already names them, and `update(dt)`'s `dt` is `Time.deltaTime`. Other
29
+ methods are PascalCase.
30
+ - **The world is mirrored on Z.** three.js is right-handed, Unity left-handed; the export negates z.
31
+ Negate z in every vector literal and every z the code computes; a rotation about x or y turns the
32
+ other way. `lookAt`, forward vectors and cameras need the same care. The prefabs are already
33
+ mirrored: only code is left.
34
+ - **A node's `position`, `rotation` and `scale` are local**: `transform.localPosition`,
35
+ `localRotation`, `localScale`. `getWorldPosition` is `transform.position`. `eulerAngles` are degrees
36
+ on both sides; three's `rotation` is radians.
37
+ - **Behaviours read as Unity's already**: `getComponent<T>` is `GetComponent<T>()`, `instantiate`,
38
+ `destroy`, `Time`, `Mathf`, `Random`, `sendMessage` keep their meaning. A prefab a behaviour
39
+ instantiates is a `GameObject` field set to its prefab asset. `findObjectOfType` is
40
+ `FindFirstObjectByType`, `findObjectsOfType` is `FindObjectsByType<T>()` (before Unity 6.6,
41
+ `FindObjectsByType<T>(FindObjectsSortMode.None)`).
42
+ - **Tweens map to DOTween's calls**, once the project has DOTween (Asset Store, free; not part of this export):
43
+ `node.doMove(to, 0.5).setEase(Ease.OutBack)` is `transform.DOMove(to, 0.5f).SetEase(Ease.OutBack)`,
44
+ `Tween.sequence().append(a).join(b)` is `DOTween.Sequence().Append(a).Join(b)`,
45
+ `Tween.delayedCall(s, fn)` is `DOVirtual.DelayedCall(s, fn, false)`, `Tween.float` is `DOVirtual.Float`,
46
+ `Tween.to(get, set, to, d)` is `DOTween.To(get, set, to, d)`, `tween.setLink(this)` is
47
+ `.SetLink(gameObject)`, and `yield tween.waitForCompletion()` is `yield return tween.WaitForCompletion()`.
48
+ A tween on a node ended with the node without being told: add `.SetLink(gameObject)`. A rotation
49
+ given as a `Vector3` is degrees in both; an `Euler` was radians, so convert it.
50
+ - **Coroutines**: a `*generator` is an `IEnumerator`, `this.startCoroutine(this.x())` is
51
+ `StartCoroutine(X())`, `yield new WaitForSeconds(s)` is the same, `yield null` waits a frame.
52
+ - **Events**: an `Event<T>` field is a C# `event Action<T>`; `listen(e, f)` is `e += f`, and its
53
+ removal belongs in `OnDestroy`.
54
+ - **Colours are `Color`**, as SceNoCo's are three's `Color`: a field the scenes wire comes across
55
+ typed. A colour written as a string in TypeScript is a bug to fix in the game.
56
+ - **Materials**: three's `color`, `emissive` and `metalness` are URP Lit's `_BaseColor`,
57
+ `_EmissionColor` and `_Metallic`, and `node.material` is `GetComponent<Renderer>().material` — a
58
+ copy of its own, as a three material written in an element is. URP has no emissive intensity: the
59
+ 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`.
61
+ - **Physics layers** came across: SceNoCo's layer n is Unity's user layer n + 7, named after the
62
+ game's own constant (`Layer.ball`), set on the objects, and the pairs `ignoreLayerCollision` set are
63
+ in the project's Physics settings. Code that names a layer adds 7.
64
+ - **Numbers**: `number` is `float`, or `int` where it counts. Keep the units: SceNoCo's are Unity's.
65
+ 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
+
72
+ ## Input
73
+
74
+ SceNoCo's `Input` is Unity's Input Manager by name; here it is the Input System, which a URP project
75
+ uses alone. The named axes and buttons are actions of the same names in the project-wide actions —
76
+ no class of your own between the game and them:
77
+
78
+ | TypeScript | C# |
79
+ | --- | --- |
80
+ | `Input.getAxis('Horizontal')`, `getAxisRaw` | `InputSystem.actions["Horizontal"].ReadValue<float>()` |
81
+ | `Input.getButtonDown('Jump')`, `getButton`, `getButtonUp` | `InputSystem.actions["Jump"].WasPressedThisFrame()`, `IsPressed()`, `WasReleasedThisFrame()` |
82
+ | `Input.getKeyDown(KeyCode.Space)` | `Keyboard.current.spaceKey.wasPressedThisFrame` |
83
+ | `Input.getKeyDown(KeyCode.JoystickButton0)` | `Gamepad.current?.buttonSouth.wasPressedThisFrame` — 1 is `buttonEast`, 2 `buttonWest`, 3 `buttonNorth`, 9 `startButton` |
84
+ | `Input.getMouseButtonDown(MouseButton.Left)` | `Pointer.current.press.wasPressedThisFrame` — a finger too |
85
+ | `Input.mousePosition`, `Input.pointer` | `Pointer.current.position.ReadValue()` (pixels, from the bottom-left) |
86
+ | `Input.mouseDelta` | `Pointer.current.delta.ReadValue()` |
87
+ | `Input.getButtonDown('Continue')` from a `data-button` | the element's click: `root.Q("banner").RegisterCallback<ClickEvent>(…)` |
88
+
89
+ `getAxis` eases toward the keys in SceNoCo and Unity's legacy Input; an action does not. Where the
90
+ easing matters, ease the value in the behaviour (`Mathf.MoveTowards` at the axis' sensitivity, 3/s).
91
+ The first scene has an `Input` object — the UI's EventSystem with its Input System module — kept for
92
+ the whole game: UI clicks need it.
93
+
94
+ ## Code outside behaviours
95
+
96
+ `Assets/Scripts/Modules` holds the rest, as TypeScript, for you to decide:
97
+
98
+ - helpers — functions — are a `static class`;
99
+ - a union of names (`'title' | 'ready'`) is an `enum`;
100
+ - a table of specs a designer tunes — a `Record` of towers, enemies, levels — is a **ScriptableObject**:
101
+ one class per record type (`TowerSpec : ScriptableObject`, a nested object a `[Serializable]`
102
+ class), one `.asset` per entry made by an Editor script run with `unity command script.run`, and a
103
+ serialized field on the behaviour that read the table, holding the assets;
104
+ - a constant only one behaviour uses is a serialized field on it;
105
+ - `main.ts` set up the renderer: its tone mapping and post-processing are a Volume (below).
106
+
107
+ ## UI
108
+
109
+ The page came across as it is, rule by rule. What code does with it:
110
+
111
+ - `getElementById` (or the page's `$`) is `root.Q("id")` on `GetComponent<UIDocument>().rootVisualElement`,
112
+ found once in `Awake` or `OnEnable`; `textContent` is `Label.text` (an element code fills is a
113
+ `Label`); `classList.add`, `remove`, `toggle` are `AddToClassList`, `RemoveFromClassList`,
114
+ `EnableInClassList`; `transitionend` is `TransitionEndEvent`; `style.left = '30%'` is
115
+ `style.left = Length.Percent(30)`.
116
+ - A `<template>` is `Assets/UI/<id>.uxml`: give the behaviour a `VisualTreeAsset` field set to it, and
117
+ `Instantiate()` where the code cloned it.
118
+ - The export says in its warnings what USS has no way to write. Change the page so it ports, and
119
+ export again: the UI is never hand-edited here.
120
+
121
+ ## Look
122
+
123
+ The project's settings are the export's, for a three.js game: Linear colour space, HDR, no MSAA (as
124
+ SceNoCo renders), Forward+ (no light limit per object, as three has none), soft shadows, and no
125
+ skybox reflections in a scene with no environment. Lights divide by π; fog and ambient light come from
126
+ the scene. Cameras draw with no post-processing, as three's default renderer does. What `main.ts` set
127
+ up in code is the port's:
128
+
129
+ - **A `Volume` in a scene came across**: a URP Volume with its profile in `Assets/Materials`, and Post
130
+ Processing on for each camera. Bloom's and depth of field's settings do not carry over by number:
131
+ tune them against the web game.
132
+ - **Tone mapping and an `EffectComposer` set up by hand** (`renderer.toneMapping`) are a URP Volume too:
133
+ a profile with Tonemapping (ACES), Color Adjustments (post exposure is log₂ of three's
134
+ `toneMappingExposure`) and Bloom, on a GameObject kept across scenes. A profile made from code needs
135
+ `EditorUtility.SetDirty` before it is saved, or its list of components is lost.
136
+
137
+ ## Checking the port
138
+
139
+ Drive both games through the same scenario and compare. The web game is driven with
140
+ `window.__scenoco` (its `help()` says how); this one with the `scenoco` commands, which take the same
141
+ verbs. They need Unity's CLI and its Pipeline package (`unity pipeline install`).
142
+
143
+ ```bash
144
+ unity command scenoco.help
145
+ unity command scenoco.import
146
+ unity command scenoco.setup --width 1080 --height 1920 # the web game's window size
147
+ unity command scenoco.play
148
+ unity command scenoco.ready # Play mode restarts the command server: repeat until it answers
149
+ unity command scenoco.pause
150
+ unity command scenoco.press --key Space
151
+ unity command scenoco.until --target Game.phase --equals playing
152
+ unity command scenoco.read --target Player
153
+ unity command capture.game_view -- --save_path Screenshots/after-start.png
154
+ ```
155
+
156
+ Step the same number of frames on both sides and the two should read the same values: 1/60 s a
157
+ frame on both clocks, the same fixed step (0.02 s) for physics. Compare values — `read --target
158
+ Ball.transform.position` here, `__scenoco.eval(...)` there — rather than screenshots: they agree
159
+ within a physics step. When a reading differs, the C# is wrong, not the scene: the scene came across
160
+ by the exporter. UI timed with `WaitForSecondsRealtime`, and UI Toolkit's transitions, run on real
161
+ time on both sides, so they do not line up frame for frame. A wait longer than the CLI's 30 s takes
162
+ `--timeout 120` after the verb.