@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.
- package/README.md +25 -5
- package/dist/cli.js +9 -2
- package/dist/convert.d.ts +35 -5
- package/dist/convert.js +74 -17
- package/dist/export.d.ts +33 -4
- package/dist/export.js +122 -7
- package/dist/input.d.ts +14 -0
- package/dist/input.js +73 -0
- package/dist/page.d.ts +25 -0
- package/dist/page.js +347 -0
- package/dist/stub.d.ts +45 -0
- package/dist/stub.js +324 -0
- package/package.json +4 -3
- package/unity/Driver/SceNoCo.Driver.asmdef +32 -0
- package/unity/Driver/SceNoCoDriver.cs +697 -0
- package/unity/KeepAcrossScenes.cs +25 -0
- package/unity/PORTING.md +162 -0
- package/unity/SceNoCoImporter.cs +440 -13
|
@@ -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
|
+
}
|
package/unity/PORTING.md
ADDED
|
@@ -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.
|