u2uethe Unity to Unreal porting toolkit

Port a Unity game to Unreal, and review it as a model, not a diff.

92.4 %of the particle emitters Unity draws are drawn in Unreal7,810 of 8,451, 673 effects built · u2ue metrics
99.97 %of 26,973 per-frame checks on the built effects hold26 checks, 8 red, each named · u2ue metrics
383 / 383game-rule results agree across Unity, .NET and Unreal: 348 to the bit, 35 within one ULPeach ULP row pinned to its bits; Unity's side run with no editor, 383 of 383 equal · u2ue digest faithful, u2ue parity
11 / 11product pillars pass their recurring checkscycle of 2026-10-18 02:12 · u2ue cycle
2,065 of 2,130misses carry a named cause: the converter's own note on that emitter, or a Unity rule measured on datatiming 650 of 670; the other 65 listed as the work, never passed · u2ue conform classes
151 of 161parts of the toolkit, read from its code, that a use case owns: its verbs, project fields, runtime types, manual pages and pillarsthe other 10 listed as the next work, never counted as owned · usecase_gaps.py
$2,738to port a second game's logic, its vendored libraries excluded, on Opus 5.5, estimated before it starts89,817 coupled lines; band $2,119 to $3,488, confidence LOW, with its reasons · u2ue estimate
90 %of that cost saved by the prompt cache$27,105 with no cache; 97.3 % of the processed tokens are cache reads · u2ue estimate

The effect, rule and miss tiles were measured on the reference port, a medium-sized turn-based tactics game (95,665 lines of game C# in 339 files) moved from Unity to Unreal; the last two price a second game, another studio's. Each tile names the command that measured it. Every number on this page is read from the toolkit's records when the page is generated, never typed.

u2ue is a toolkit that moves a Unity game to Unreal Engine 5. Its own tools convert what is not game logic - particle effects, scenes, UI, materials - and hold each result to Unity on numbers; the asset families that still need a person are listed under Proof it runs. The game's logic is ported by an AI model following the toolkit's written skill. A reviewer then reads a UML model instead of the code line by line: every use case step names the command that proves it, the classes it touches and the page it was read from.

Price it, then run it. u2ue estimate reads a Unity project, with no editor, and says what the port will cost on Opus 5.5 - tokens, dollars, the share the prompt cache serves, a band and a confidence with its reasons - from rates measured on a real port. u2ue port then runs the whole port as one command: every stage read from its own records, run where a verb can, stopped with one question where a person, the AI or a Unity editor is needed.

Where the logic goes. A MonoBehaviour holds the game's state, runs its rules and draws, and Unreal can run none of it. A port moves the state and the rules into an engine-free model in plain C#, shaped as Model, View and Controller with commands going in and events coming out; Unity and Unreal each keep only the part that draws, so both engines run the same rule code and their answers can be compared bit for bit. The manual explains the shape a port moves into and shows one rule moved, before and after.

The full manual is on this page after the overview: installation and a tutorial, every procedure, the hard parts in depth, every command, the architecture, troubleshooting and questions.

How a reviewer reads it

The epic: one game, Unity to Unreal

EPIC-1 is the table of contents. Each stage names the use case that carries it, and each of those was read from a manual chapter or a skill. Click any case to open it below.

1 The porter finds what the toolkit holds for their question
2 The porter describes the project: Unity root and version, the Unreal project, the work folder, the adapter
UC-11UC-17
3 The tool inventories the game: every MonoBehaviour, the Unity APIs it calls, the scenes and prefabs, the effects
UC-11UC-17UC-14UC-15
4 The porter (or Opus, through the u2ue-logic skill) moves the rules out of the MonoBehaviours into an engine-free model, behind a platform seam and a view seam
UC-11UC-14UC-15
5 The porter implements the Unreal adapters for those seams: view, input, camera, effects player, platform services
UC-11UC-14UC-15UC-16
6 The tool converts the transform chain and the scenes: axes, units, rotation order, scale, hierarchy
UC-11UC-14UC-12
7 The tool ports the effects
UC-11UC-17UC-13UC-19
8 The tool proves parity and reports it
UC-11UC-17UC-15UC-07
9 The game owner answers the decisions the page asks, and only theirs
UC-11

3a The game's effects are chosen by its code, not by its prefabs   4a A MonoBehaviour WAITS (coroutines, Invoke, yield)   6a A node has a non-uniform scale under a rotation   7a A rule the conversion needs is not measured   8a The project's Unity version differs from the one the rules were measured on   8b A frame differs only because one engine drew one random sample

The use case model

A UML use case diagram, drawn from the model - 21 cases, 5 actors, the system boundary. Each case shows the epic step it is «include»d for, or where it «extend»s the epic (the arrow of an extend points from the extension to the base, the opposite of an include).

u2ue - the Unity to Unreal toolkitEPIC-1 · kite (summary)Port a Unity game to Unreal and show how identical it isporterporting a gameUC-08The porter holds every keyof a build to Unity onnumbersUC-12The porter imports a Unityscene as an Unreal leveland grades it«include» EPIC-1 step 6UC-14The porter moves a game'scode into an engine-freemodel«include» EPIC-1 step 3, 4, 5, 6UC-16The porter lays out thegame's uGUI screens inUnreal«include» EPIC-1 step 5UC-17The porter takes a new gamefrom its project file toits first report«include» EPIC-1 step 2, 3, 7, 8UC-20The porter verifies thetoolkit on their machineopusthe AI modelUC-11Prove it before reportingit«include» EPIC-1 step 2, 3, 4, 5, 6, 7, 8, 9UC-13Opus ports one effect gapby the route protocol«include» EPIC-1 step 7UC-15Record the slice and takethe next one«include» EPIC-1 step 3, 4, 5, 8UC-19Opus runs the effectpipeline from the prefabsto the metrics«include» EPIC-1 step 7toolkitits own runnersUC-10The toolkit measures aUnity behaviour in theowner's idle editor«extend» EPIC-1 at 7aownerwhose product it isUC-07The owner checks everypillar of the product eachcycle«include» EPIC-1 step 8UC-18The owner assembles thetoolkit's repository fromits own treesdeveloperextending the toolkitUC-01A developer lands aconverter route behind aswitchUC-02A developer answers onegame-specific question withan adapter«extend» EPIC-1 at 3aUC-03A developer ports a Unityshader's material familyUC-04A developer makes theconverter read a rulemeasured in UnityUC-05A developer gives a tool aselftest the check runsUC-06A developer adds a verb tothe facadeUC-09A developer moves a toolonto the project file

The class model it steers

Extracted from the code by the same tool that gates it: 30 verbs of the command-line facade (Python, 154 types and modules) and 20 types of the runtime library a ported game runs on (C#). Pick one to see its members and the use case steps that run it or name it.

The facade: py -m u2ue <verb>
The runtime: U2ue.Runtime

Count what is missing - two denominators

A model graded against its own list cannot come back low: the list is only what it already holds. So the model is also counted against the toolkit's real surface, read from the code - every verb, every project field, every runtime type, every manual page, every pillar.

Against its own list: 135 of 135 steps (100 %)
Against the code: 151 of 161 surface items (94 %)
kindowned by a use case
document42 of 42
pillar11 of 11
project field49 of 59
runtime type19 of 19
verb30 of 30
What no use case owns yet
project file: estimate_basis (7 fields)project file: unreal (3 fields)

This list is the next work. A gap here is not a failure; an unmeasured gap would be. Left out of the count on purpose - a page made from the model cannot also be one of its sources, and the hook page states no requirement: 17-use-cases.md (generated from the model); 19-facade.md (generated from the code and the model); a4-traceability.md (generated from the model); why-u2ue.md (the hook: a sales page, not a requirement).

An AI ports the game logic, and the toolkit says where it stands

The game's logic is the one part not converted automatically: an AI model ports it, following the toolkit's skill, one slice at a time. On a second game - a different studio's project, on an older Unity - this is where that port stands, each step judged by its own observable from the project's records the moment this page was generated (u2ue logic). A step the toolkit cannot see says so: a reviewer's call, or a test run it names.

0
name the project DONE
1
Read the game before touching it DONE
2
Draw the class model of ONE slice before moving anything (UML steers) DONE
3
Sort the slice's types and members JUDGED
4
Cut the Core DONE
5
Put the platform seam in first DONE
6
Move the slice's rules into the Core DONE
7
Emit events; replay them NOT RUN
8
Keep Unity's frame order NOT RUN
9
Prove it: the same answers, by the bit DONE
10
The Unreal host DONE
11
Record the slice and take the next one DONE

Its Unreal side is that game's own Unreal project, made by the toolkit the way a customer would make one - from the host template, plugins cloned at pinned commits, compiled, its managed project generated, wired to the model and run headless: 8 of 8 steps proven by their own log lines, 9.2 minutes from nothing to the host's first answers, and those answers equal, bit for bit, the headless engine's.

Proof it runs

The product makes 11 promises, called pillars, and each has checks that hold it there. A check that has only ever passed proves nothing, so each one is first made to fail on a planted defect. ABSENT means no check exists yet - it is never counted as a pass.

#PillarThe promiseChecksVerdict
1Auto-portevery asset family that is not logic ports with no human step6 + 4 absentPASS
2AI logic portOpus, pointed at a game through the skill, ports its logic8 + 1 absentPASS
3Human ergonomicsevery concept a named class; diagrams generated from the code and gated8PASS
4Automation tools shippedthe Unity and Unreal automation a port needs ships in the package5PASS
5Proof and conformanceevery judge has a plant that fails; conformance read from data5PASS
6Measured knowledgeevery Unity rule measured by a probe case, stored per Unity version6PASS
7Generic, not one gameadapters and project files, no hard-wired paths in the core5 + 1 absentPASS
8Packaging and releasea UPM package that installs into a fresh Unity and a fresh Unreal project2 + 2 absentPASS
9Speed and proof of valuethe porting speed and the percent-identical family, from records1 + 1 absentPASS
10Safe operationthe toolkit never disturbs the person using the machine3PASS
11Run infrastructurepinned, resumable runs from data, stoppable between steps5PASS

Not covered yet (ABSENT), each a promise with no check behind it: pillar 1: audio: a Unity AudioClip / AudioSource ports with no human step; pillar 1: materials / meshes / textures outside effects; pillar 1: animation; pillar 1: lighting / cameras; pillar 2: a logic slice of the second game ported through the skill; pillar 7: a second game end to end in its own .uproject; pillar 8: the package layout; pillar 8: a clean install; pillar 9: the second-game benchmark.

The game's rules, by the bit. The same rule cases run on Unity's Mono, on .NET and inside Unreal, and every float is compared as its bit pattern. 383 rows; 35 differ by exactly one ULP, all of them Mono keeping a float wider between operations, which the C# standard permits - each pinned to its exact bits, so a new difference is still red. Unity's side needs no editor: the toolkit runs the project's own Unity version's Mono standalone, and its 383 rows match the editor's 383 exactly.
It never takes the machine from the person using it. A Unity measurement runs only in an idle window (ten quiet minutes), stops the moment the owner returns, and never answers a dialog it did not open. An Unreal trial is a data file, one headless Unreal at a time, stoppable between steps. 32.8 h of build time over 673 effects so far, a median of 100 s each.

The toolkit

The facade, the converter, the measured rules, the Unity and Unreal tools, the skills and the manual are one repository, assembled from the toolkit's own trees by u2ue release. It is private until its licence is chosen and every file reads as public copy.

Every number on this page was read when it was generated (showcase.py): u2ue metrics, u2ue parity and u2ue digest faithful on the reference project; u2ue estimate on the second game; the last full u2ue cycle; usecase_gaps.py; uml.py extract. A number that cannot be read stops the build - nothing here is remembered or typed.

The manual

34 pages, 155,940 words: why u2ue exists, installation and a tutorial, every procedure, the hard parts in depth, the use cases, every command, the architecture and its UML, troubleshooting, and questions and answers. Its own contents list every chapter.

Why u2ue

Who this is for: the evaluator deciding whether to use u2ue - what it does, what it has proved, what it costs and what is not done yet, on one page.

Port a Unity game to Unreal Engine 5, and prove it is still the same game.

What it does

u2ue is a porting toolkit behind one command line, py -m u2ue, called the facade; each of its commands is called a verb. It reads the Unity project as text (the YAML files Unity saves scenes, prefabs and materials in), with no editor running. It converts what is not game logic: particle effects, scenes, UI, materials and audio (the steps that are still manual are listed below). It measures in Unity any behaviour that has to be matched exactly. It holds the result to Unity on numbers, frame by frame and bit by bit. The game's logic is ported by an AI model following the toolkit's own skill (a written procedure the model loads as its instructions), and a reviewer judges that port by reading a generated UML model (diagrams of how the code is built and what it is for; Reading UML and use cases teaches them) instead of a diff.

What sets it apart, each with the chapter that has the details:

  • A price before you start. u2ue estimate prices the port of your Unity project on Opus 5.5 (an Anthropic AI model), in tokens (the units a model reads and writes, and is billed by) and dollars, with a band (a low and a high figure) and a confidence level, from rates measured on a real port. It needs no editor and no project file (the one JSON file that describes a game to the toolkit). What a port costs.
  • One command for the whole port. u2ue port runs every stage a verb can do, and stops with one question where a person, the AI or a Unity editor is needed. Chapter 4.
  • It reads Unity without Unity. Prefabs, variants, scenes, materials and ScriptableObjects are read from their YAML, and the textures Unity actually samples from Library/Artifacts (where Unity keeps its imported copy of each texture). Nothing steals focus or blocks the person working. Chapter 6, Chapter 11, Chapter 12.
  • Shuriken to Niagara, with evidence. The toolkit's converter turns effects made with Shuriken, Unity's particle system, into Niagara, Unreal's. Every behaviour added to the converter lands as a route (its handling of one Unity behaviour) behind a switch (an environment variable that turns that route on or off), and the switch turns ON only with an evidence row: the record of the trial (the route tried on real effects first) that proved it. What it cannot port is named per emitter (one particle system inside an effect), with the reason. Chapter 7, Chapter 11.
  • It measures Unity instead of guessing. A probe (an Editor C# script that sets up a case in Unity and records what happens) measures how Unity behaves, only while the person at the editor is idle, and each rule keeps the Unity version it was measured on. Chapter 8.
  • The same bits on every runtime. The game's rules run on .NET, on the target Unity version's own Mono (the runtime Unity runs C# on) with no editor, and in Unreal, and their answers are compared by float bits, a check called parity (u2ue digest, u2ue parity). Chapter 5, Chapter 14.
  • Data first, pictures last. Unity's own particle state is held against Niagara's read-back (Unreal's particles, recorded frame by frame) for every emitter (u2ue conform), and every miss (an emitter whose particle count or first birth disagrees with Unity's) is listed, most with a named cause. Chapter 9.
  • Checks that can fail. Every judge (a script that holds a result to a rule) must refuse a planted fault, a defect put there on purpose (u2ue judge --prove), and u2ue cycle checks every promise of the product, called a pillar, on each recurring run: a promise with no check reads ABSENT, never PASS. Chapter 14.
  • Headless on both sides. Headless means run with no window open, so nothing takes the screen's focus. Unity's Editor-folder tests (the NUnit tests Unity normally runs inside its editor) and a C# type-check run with no Unity Editor. Unreal runs headless, and u2ue host makes the game's own Unreal project. Chapter 12, Chapter 13.
  • Built for an AI porter, and checked. The toolkit's skills tell an AI model how to port a game's logic and an effect gap (an emitter Unity draws and Unreal does not). Each step of the logic skill names the command it runs and when it is done, and a gate (a check that refuses a result breaking one rule) refuses a skill that names a command the toolkit lacks. Chapter 15.
  • A model to review, not a diff. The use cases (each goal, told as numbered steps), the requirements, the class model (which classes the code holds and how they use one another) and the traceability (the chain from each requirement to the check that proves it) are generated on every build from the code and the toolkit's own documents, and every use case step cites the page it was read from. Chapter 17, Chapter 22, Appendix E.
  • Never a silent default. Every value is READ from the source, MEASURED in Unity, or ABSENT (proven missing, or unreadable), with where it came from or the reason. Chapter 1.

What it has proved

Each tile is printed on every build from the showcase record (the file in which the toolkit records its headline numbers, named under the tiles), never typed by hand. The effect, parity and conformance tiles were measured on the reference port, a commercial Unity 6 tactics game moved to Unreal Engine 5.7; the last two price a second, unrelated game.

The tiles use a few words of their own. A ULP (unit in the last place) is the smallest step between two floats, so two results one ULP apart differ by the least two floats can. A seam is an interface the game's rules call instead of an engine API, and each engine's host code fills it. Coupled lines of code use a Unity API, and the prompt cache serves the part of each AI call the model has read before, at a fraction of the price. Reading UML and use cases explains the use case tiles, What a port costs the last two, and the glossary (Appendix C) every other term.

92.4 %of the particle emitters Unity draws are drawn in Unreal7,810 of 8,451, 673 effects built · u2ue metrics
99.97 %of 26,973 per-frame checks on the built effects hold26 checks, 8 red, each named · u2ue metrics
383 / 383game-rule results agree across Unity, .NET and Unreal: 348 to the bit, 35 within one ULPeach ULP row pinned to its bits; Unity's side run with no editor, 383 of 383 equal · u2ue digest faithful, u2ue parity
11 / 11product pillars pass their recurring checkscycle of 2026-10-18 02:12 · u2ue cycle
2,065 of 2,130misses carry a named cause: the converter's own note on that emitter, or a Unity rule measured on datatiming 650 of 670; the other 65 listed as the work, never passed · u2ue conform classes
151 of 161parts of the toolkit, read from its code, that a use case owns: its verbs, project fields, runtime types, manual pages and pillarsthe other 10 listed as the next work, never counted as owned · usecase_gaps.py
$2,738to port a second game's logic, its vendored libraries excluded, on Opus 5.5, estimated before it starts89,817 coupled lines; band $2,119 to $3,488, confidence LOW, with its reasons · u2ue estimate
90 %of that cost saved by the prompt cache$27,105 with no cache; 97.3 % of the processed tokens are cache reads · u2ue estimate

Measured on the reference port and recorded 2026-10-18 15:38 by u2ue/survey/showcase.py --record (toolkit commit 8538bff); every tile names the command that produced it.

Why the numbers can be trusted

u2ue's iron law is one principle: propose from a fixed space, verify by execution, report a measured confidence, refuse rather than invent. Applied to a port:

the principle u2ue
propose from a fixed space every value is READ from the source, with where it came from; a symbol must be one the class model holds
verify by execution a Unity behaviour is READ from source or MEASURED in Unity by a probe; every change runs a judge, and every judge has a plant it must refuse
report a measured confidence every number names its record and its denominator; a stale input prints STALE
refuse rather than invent a value that cannot be read is ABSENT, with the reason; a miss in an index (one of the toolkit's lookups of what the code holds) is UNKNOWN, never ABSENT

The same principle holds the AI porter's work. The model proposes; the class model and the index are the fixed space its proposal must land in; the gates verify by running, and each refuses a planted fabrication: the class-model gate a method name the code lacks (uml.py selftest), and the manual's command gate an option the facade does not read. The toolkit never relies on the model not to invent; it makes an invention fail, by name, before anyone reads it. What it has not shown is a token saving: on exact-name lookups the index saved none (Chapter 15).

What it costs

The game's logic is the one part an AI writes, and that is where the model tokens go; every other stage is run by a verb. Ask for the price of your own game before you start. It opens no Unity and no Unreal, and needs no project file:

py -m u2ue estimate --unity <your Unity project> --roots <the game's code folders>

What a port costs shows estimates for two real games, the measured rates they multiply by, what the toolkit saves, and how sure the number is, with the reasons.

What is not done yet

  • The logic is not automatic. The toolkit gives the method, the runtime, the analysis and the gates. An AI model following the logic skill, or a person, moves the code and writes the Unreal hosts (Chapter 1, Chapter 5).
  • Animation and physics are not covered. The reference port had neither, so no tool is claimed.
  • Some steps are tools, not verbs yet: a scene's middle steps, between importing it into Unreal and reading the saved level back (textures, material parents, lighting, outline hulls: the extra material slot per mesh that draws the toon outline Unity's outline pass draws).
  • Not yet proven in Unreal: drawing Unity's trails and the host templates' headless smoke run. The UI capture refuses by name until it ships in the package, and the lit-material and Timeline routes sit behind switches that are still OFF.
  • Not yet a released package. The Unity package (package.json, a versioned release) and the probes as its Editor assembly (code Unity loads only in its editor) are still open, and many effect and scene tools, and the tools that queue and report effect work, still default to the reference port's folders. Each is moving onto the project file's variables, proven by its selftest (the tool's own check of itself) and an unchanged output (Chapter 18, "Converting a tool"); u2ue cycle counts the hard-wired sites (code that names one game, machine or person) left in the toolkit's core, and that count may only go down. The toolkit's parts live in two trees today: u2ue/tools.py names each part's folder once, U2UE_TOOLKIT_ROOT moves them as a whole, and u2ue release assembles them into one repository (Chapter 20).
  • There are a lot of switches. Chapter 21 counts them, generated. Each is a proof trail; the permanently-on ones are to be retired in one pass that whole_trace (the offline replay that proves a converter change) shows changes nothing.
  • The probes need the owner's Unity editor, and run only while it is idle. Nothing in the window protocol (the guarded session in which the probes run) depends on whose editor it is, so a team could run it on a dedicated machine.
  • The Unreal hosts depend on UnrealSharp (the plugin through which Unreal runs their C#), which had no console path and no production promise when it was last checked.
  • Two games so far: the reference port and a second, unrelated game, one short of the rule of three (a reusable part is general only once three different applications have used it).

Appendix B has the plan for every item above that is planned, and what ends it. Appendix D has the sources for the last two.

Where to go next

About this manual has a reading path for each.

About this manual

Who this is for: every reader, on the way in - which part of the manual is yours, the path through it, and the conventions it is written in.

Edition 2026-10-17. The manual of u2ue, the Unity to Unreal porting toolkit. It assumes you know Unity and Unreal as a user, Python well enough to run a script, and C# well enough to read a MonoBehaviour.

Three readers, three parts

The manual is divided by who is reading it. Find your part, then your path below.

part for what it holds
Part I the evaluator deciding whether to use u2ue Why u2ue (what it does, what it proved, what is not done yet), this page, Reading UML and use cases (the diagrams and case pages, before any page assumes them), What a port costs, Porting to Unreal in a nutshell (a quick start, and the five problems every port meets), The short version (every aspect of a port on one screen each), 1. Introduction (exactly what it is and is not)
Part II the porting developer porting their own game, a person or an AI model 2 Concepts, 3 Installation and the project file, 4 Tutorial, 5 Porting the game code, 6 Transforms, scenes, UI and audio, 7 Effects, 8 Measuring Unity, 9 Verification and gates, 10 Metrics and reports, 11 Shuriken to Niagara in depth, 12 The Unity tools, 13 The Unreal tools, 14 Test-driven porting, 15 Porting with Opus 5.5, 16 Troubleshooting, Questions and answers
Part III the toolkit developer extending u2ue, and the reviewer checking it 17 Use cases, 18 Extending the toolkit, 19 The facade's requirements, 20 Commands, 21 Reference, 22 Architecture and the UML
Appendices evidence and look-up, for every reader A. A worked example (the reference port in numbers), B. Roadmap (what is left), C. Glossary, D. Prior art (other ways to port), E. Traceability

Part II runs in the order ISO/IEC/IEEE 26514 (the international standard for user documentation) gives a user manual: concepts, installation, a tutorial, procedures, troubleshooting.

Reading paths

  • New to UML or use cases: Reading UML and use cases first. It is every symbol and field the manual uses, and nothing it does not.
  • Deciding whether to use it: Why u2ue, then What a port costs with u2ue estimate run on your own project, then Chapter 1. Appendix A is the reference port in numbers, Appendix B what is left to do, Appendix D the other ways to port.
  • Porting your game: price it with py -m u2ue estimate --unity <your Unity project>, describe it in a project file (Chapter 3), then run py -m u2ue --project <game> port and port --run (Chapter 4, its first section). Where port stops for the logic, go to Chapter 15 and Chapter 5; for any other part, its Part II chapter as you reach it, with Chapter 16 open beside you.
  • An AI model doing the port: Chapter 15 first, Chapter 2, then the entry skill (u2ue/skill/u2ue/SKILL.md), which hands the logic to u2ue/skill/u2ue-logic/SKILL.md and an effect gap to u2ue/skill/u2ue-port/SKILL.md; Chapter 14 for how its work is checked, and Chapter 20 for each command.
  • Extending the toolkit: Chapter 2, Chapter 18, Chapter 14, Chapter 22.
  • Reviewing a port or the toolkit: Why u2ue, Chapter 17 (start at the epic, the one use case that strings the others together), Chapter 22 (the architecture and the UML), Chapter 19 (each command as a requirement), Appendix E.

If you want to

if you want to read
know what porting your game will cost What a port costs
know exactly what the toolkit is and is not 1. Introduction
get going in five minutes Porting to Unreal in a nutshell
understand projects, adapters, verbs, routes and windows 2. Concepts
install it and describe your game 3. Installation and the project file
run a first port end to end 4. Tutorial
port the game's code: MonoBehaviours, coroutines, data 5. Porting the game code
convert transforms, scenes, UI and audio 6. Transforms, scenes, UI, audio
port the particle effects, materials and lights 7. Effects, then 11. Shuriken to Niagara
measure a Unity behaviour exactly 8. Measuring Unity
prove that a port is right 9. Verification, 14. Test-driven porting
report how identical it is, and how fast 10. Metrics and reports
drive Unity headless, live, or from several AI agents at once 12. The Unity tools
run Unreal headless, make the game's Unreal project 13. The Unreal tools
run the port with an AI model, save its tokens, review its work 15. Porting with Opus 5.5
get past a known trap 16. Troubleshooting
see every goal it serves, step by step 17. Use cases
add an adapter, a verb, a route or a probe 18. Extending the toolkit
know exactly what a command accepts and refuses 19. The facade, 20. Commands
find a format, a switch or a tool 21. Reference
review the design and its UML 22. Architecture and the UML
see what is left to do B. Roadmap
compare it with other ways to port D. Prior art

Examples

Every example in this manual is real: its commands ran, and its output was recorded on the game named beside it.

  • A first port, start to finish - Chapter 4: a second, unrelated game (Unity 2021.3) from its project file to its first report, with what each step printed; then its code, scenes, UI, Unreal project and conformance.
  • The reference port in numbers - Appendix A: what was ported, how, and what it measured.
  • Porting one effect gap, in depth - Chapter 11, from the census (an offline count of the emitters a new route would gain) to the flip (its switch turned ON) with its evidence row.
  • A game's own Unreal project made from nothing - Chapter 13, measured step by step on the second game.
  • A test for a newly ported rule - Chapter 14, from the rule to the cycle.
  • Recipes for extending the toolkit - Chapter 18: a game adapter, a verb, a converter route, a material family, a measured rule, a selftest, a concept, and converting a tool onto the project file.
  • Every goal as a fully dressed use case - Chapter 17, each step citing the page it was read from (Reading UML and use cases explains the form).

Conventions

  • The reference port - the commercial Unity 6 tactics game moved to Unreal Engine 5.7 that the toolkit was built on. The second game - a different studio's project on Unity 2021.3, run through the same facade to show what is general.
  • READ - a value taken from the Unity source (a file, a field) with where it came from.
  • MEASURED - a Unity behaviour observed in Unity itself by a probe, judged by a judge that refuses a planted wrong answer.
  • ABSENT - a value proven not to exist, or not readable, named with the reason. There is no fourth category: the toolkit never substitutes a plausible default, and a refusal is reported by name.
  • HAVE / NOT YET - whether the toolkit itself provides something today. NOT YET is always followed by the plan that delivers it.
  • Commands run from the toolkit's root folder: py -m u2ue .... Sample output is real; a project's name is written <game> and machine paths <work>/..., <unity project>, <unreal project>.
  • "Chapter N" and "Appendix X" are links in the one-page edition.

How the manual stays true to the code

The parts that describe the code (the command reference, the facade's requirements, the use cases, the class model, the switch, tool and selftest tables, the traceability) are generated from the code and the requirements model on every build, so the manual cannot describe a toolkit that has moved on. The requirements model is the toolkit's use cases and requirements, each step citing the page it was read from (Chapter 17 and Appendix E). The build refuses a page that names a particular game, its folders or a machine path, shows a command or an option the facade does not have, or names a tool file the package does not ship.

The toolkit's earlier documents beside the code (u2ue/README.md, u2ue/GUIDE.md, u2ue/BASICS.md, u2ue/ARCHITECTURE.md, u2ue/CONCEPTS.md, u2ue/USECASES.md, u2ue/PACKAGE.md, the u2ue-port and u2ue-logic skills, and four other notes, among them vfxport/README.md) are folded into this manual, so a person need not read them; the skills stay the prompts an AI model loads. u2ue/manual/coverage_gate.py checks that every section of each is here, or is named as out with the reason.

Those earlier documents, the toolkit's survey of itself (u2ue/survey/), the manual's builder and the pillar cycle are the toolkit's OWN: they stay in its repository and a release does not ship them; a release's RELEASE-excluded.tsv names each with the reason, and u2ue check in a release reports their selftests as not run, with that reason. A page that names one says how the toolkit holds itself to its promises; it is not a command a release can run.

The Markdown files in u2ue/manual/ are the source. In the toolkit's repository, py u2ue/manual/build.py regenerates the generated parts and writes manual.html, the single-page edition; py u2ue/manual/build.py --check exits 1 when a generated part is stale, and py u2ue/manual/build.py --selftest proves the gates still refuse their plants.

Reading UML and use cases

Who this is for: every reader who has not used UML or use cases before - after it you can read every diagram and use case page in this manual. Read it before any page assumes it.

This manual shows the toolkit, and the method it gives a port, in two kinds of model: diagrams of how the code is put together, and use cases that say who wants what done and how they get it. Both come from UML, the Unified Modeling Language: a standard set of diagram kinds for describing software, kept by the Object Management Group. You do not need the standard to read this manual. This page is everything it uses, and nothing it does not.

Why a porting manual uses UML

A port is mostly moving code into a new shape: rules out of Unity's MonoBehaviours into a model that knows no engine (Chapter 5). A diagram of the shape you want is a shorter, checkable description than prose. The method is to draw the target first and then make the code match it, and an AI model doing the port is given the diagram as its instructions (Chapter 15). The generated diagrams are held to the code, so a diagram here is a checked fact, not a drawing ("The rules this manual holds its UML to", below).

The three diagram kinds

The diagrams are written in Mermaid, a text format that draws diagrams in a web page. Mermaid has no use case diagram, so this manual draws use case diagrams as flowcharts and says so where it does.

  • Class diagram: the STRUCTURE. Which things exist (classes) and how they use one another. Chapter 22's concept model (the toolkit's main ideas, each held by one class) is one.
  • Use case diagram: the GOALS. Who uses the system (actors), for what (use cases), and how the goals depend on one another. Chapter 17 has the toolkit's.
  • Activity or flow diagram: the ORDER. Steps, the arrows between them, and the checks between steps. Chapter 17 draws the epic (the whole port as one use case, explained below) this way, generated; the short version and Chapters 7 and 14 sketch a pipeline this way by hand. Chapter 5 and Chapter 22 also use the flowchart form for structure: Chapter 5's model and its hosts, Chapter 22's layers and its facade map (each verb and the tools it runs; its caption gives its legend).

A UML glossary: every symbol this manual draws

In a class diagram

The concept model in Chapter 22 uses the first three rows. The toolkit's class model is printed there as a table, because a diagram of over a hundred boxes is unreadable at page width; py u2ue/survey/design_diagram.py OUT.mmd draws it, with the last two rows.

what you see its name what it means here
a box with a name on top class one idea the code holds as one class. In the concept model the first line under the name says what it is in plain words (this manual's own habit, not standard UML), and the lines after it are its main members
name() inside a box method something the class does; a name without brackets is data it holds
a solid arrow A --> B with a label association A uses, asks or holds B, and the label says how ("Project --> Adapter : asks" reads "a Project asks its Adapter")
a dashed arrow dependency A imports B
a hollow triangle at one end generalisation the class at the plain end is a kind of the class at the triangle, its base

In a use case diagram (drawn as a flowchart)

what you see its name what it means here
a dashed box outside the boundary actor a role that wants something from the system: a person (the porter, the game's owner, a developer), the AI model, or the toolkit's own runners (the scripts that, for example, measure Unity in an idle editor). A role, not a person: one person can play several
the large box around the cases system boundary what is inside is the toolkit; what is outside uses it
a rounded shape with an id (UC-07, EPIC-1) use case one goal an actor can reach, named as a goal ("The owner checks every pillar of the product each cycle")
a plain line between an actor and a case association that actor takes part in that case
a dashed arrow labelled include include the base case always does the included case as part of itself; the arrow runs FROM the base TO the case it includes
a dashed arrow labelled extend extend the extending case runs only when a condition at one step of the base holds; the arrow runs FROM the extension TO the base, the opposite way to include

In a flow diagram

what you see what it means
a box one step, or in a structure sketch one part
a solid arrow then: the order of the steps; in a structure sketch, "uses"
a label on an arrow the command that moves from one box to the next (Chapter 7), or what passes between them (Chapter 5)
a diamond a gate: what is checked before the next step (Chapter 7)
a cylinder stored data: files one step writes and the next reads (Chapter 7); in Chapter 22's facade map, a folder of tools
a six-sided box an extension: where the step it hangs from can go wrong (Chapter 17's epic)
a circle the start or the end (Chapter 17's epic)
a dashed arrow not the main order: an input that feeds a step (the short version: measuring Unity), or a branch to an extension (Chapter 17's epic). Chapter 22's facade map uses it for a tool a verb runs, and says so
a box drawn around boxes a group: the boxes inside are one part (Chapter 5's engine-free model, Chapter 22's facade map)

The symbols, drawn

The three small diagrams below are drawn the way the manual's own diagrams are, with made-up names, so each symbol can be seen once before it is met in a real one.

A class diagram. Project and Adapter are classes: the name on top, then members (a name with brackets is a method, one without is data). The solid arrow is an association, read along its label: a Project asks its Adapter. The dashed arrow is a dependency: Cli imports Project. The hollow triangle points at the base class: GameAdapter is a kind of Adapter.

classDiagram
    class Project {
        name
        env()
    }
    class Adapter {
        effect_keys()
    }
    class GameAdapter
    class Cli
    Project --> Adapter : asks
    Cli ..> Project
    Adapter <|-- GameAdapter

A use case diagram, as a flowchart. The dashed box outside is an actor, the large box is the system boundary, the rounded shapes are use cases. The base case always does the case it includes; the extending case runs only on a condition, and its arrow points the other way, back at the base.

flowchart LR
    porter["porter"]:::actor
    subgraph toolkit["the toolkit"]
        port(["UC-A Port a game"])
        effects(["UC-B Port the effects"])
        measure(["UC-C Measure a rule in Unity"])
    end
    porter --- port
    port -. include .-> effects
    measure -. extend .-> port
    classDef actor fill:none,stroke-dasharray:3 3

A flow diagram. Boxes are steps, solid arrows the order, the diamond a gate checked before the next step, the cylinder stored data one step writes and the next reads.

flowchart LR
    read["read the effect"] --> ir[("the IR files")] --> build["build it in Unreal"] --> gate{"does it hold to Unity?"}
    gate -- yes --> report["report it"]

What a use case is

A use case is one goal of one actor, written as a short story in numbered steps that ends with the goal reached, plus the ways the story can go wrong. It is not a feature list and not a method of the code: "The porter takes a new game from its project file to its first report" is a use case; build() is not. This manual writes use cases in the "fully dressed" form Alistair Cockburn describes in Writing Effective Use Cases, and every case in Chapter 17 is laid out the same way:

field what it holds
name the goal, as an active phrase
level how big the goal is: kite (a summary that strings several goals together - an epic), sea (one goal a user sits down to reach, the level to prefer), fish (a step inside another goal)
primary actor the role whose goal it is; supporting actors are the others it needs
stakeholders who else cares about the outcome, and what each wants
trigger what starts it
scope what the case covers
precondition what must already be true for it to start
minimal guarantee what holds even when it fails (here: nothing is dropped silently)
success guarantee what holds when it succeeds
main success scenario three to eleven numbered steps, each naming what it needs; outside that range the goal is the wrong size
extensions where it can go wrong, each numbered by its step: 3a branches from step 3, * from any step
read from the document the case was read out of
proven by the command that checks a step; that command is the test, and it must fail on a planted defect before it is trusted

An epic is the kite-level case that strings the others together: EPIC-1, "Port a Unity game to Unreal and show how identical it is", is the whole port, and each of its steps names the cases that carry it. A reviewer starts there (Chapter 22).

The chain, and the requirements it finds. Each step's result is the next step's precondition. When a step needs something no earlier step guarantees, the chain has found a requirement nobody wrote down. It is marked INFERRED and goes to the owner to confirm. A step that names code which exists is marked HAVE with the real name.

How to read a use case page

  1. Read the name and the primary actor: whose goal, and what.
  2. Read the success guarantee: what is true at the end. Then the minimal guarantee: what is true even when it fails.
  3. Walk the main success scenario. For each step ask what it needs and whether an earlier step gave it.
  4. Read the extensions. They are where a real port goes wrong; Chapter 16 is the same branches by symptom.
  5. Run a step's "proven by" command instead of taking the step on trust.

The rules this manual holds its UML to

  • Generated, then gated. Every UML view is regenerated on every build: the class model and the facade map from the code's own imports and bases, so they cannot name what the code lacks; the facade's requirements (what each verb accepts and refuses) from each verb's own code; the use case model and the traceability from the requirements model, and a use case that cites a page the manual no longer has stops the build; the concept model from u2ue/CONCEPTS.md, whose gate checks on every u2ue cycle run that each concept it calls a class exists in the code (Chapter 22).
  • Sketches are named as sketches. The flowcharts of the short version and Chapters 5, 7 and 14, and Chapter 22's layer sketch, are drawn by hand: they show an order or a shape, and no gate checks them.
  • The model comes first. A new idea is drawn as a class before the code is written, and a step of the logic port draws the target diagram before any code moves (Chapter 5, step 2 of the playbook; Chapter 18, "A concept").
  • One idea, one class. Each concept in the concept model names the class in the code that holds it. The manual's terms are defined once, in the glossary (Appendix C).

What a port costs

Who this is for: the evaluator deciding whether to use u2ue - what porting your game will cost in model tokens and in dollars on Opus 5.5, worked out before you start, and how sure that number is.

Every figure on this page comes from a record. The generated block below holds them, and the sections after it say what they mean: processed and new tokens and the rates under "What the number is made of", the bands and the leave-one-out figures under "How sure it is".

Ask it about your own game

py -m u2ue estimate --unity <your Unity project>                          every folder under Assets, each listed with its lines
py -m u2ue estimate --unity <your Unity project> --roots Assets/Game      only the folders that are the game's own code
py -m u2ue estimate --unity <your Unity project> --exclude <a folder>     leave out a vendored library, which is replaced, not ported

It reads the project's files: it opens no Unity and no Unreal, and it needs no project file. It prints five things:

  • the code to move, split into coupled lines (they use a Unity API, a lifecycle method or a Unity base class) and pure lines (plain C#);
  • the tokens for each stage;
  • how many of those tokens the prompt cache serves;
  • the cost at Opus 5.5's list price, with the cost of the same calls without caching beside it;
  • a band, and a confidence level with its reasons.

With no --roots, every folder under Assets is counted and listed, because vendor packages (third-party code copied into the project) live there too. The logic figure is then an upper bound. Name the game's own folders, leave out the libraries it vendors, and run it again: the third row below is the second row's game with its two vendored libraries excluded.

Real estimates

project coupled lines pure lines processed tokens (band) of them new Opus 5.5 list cost (band) with no prompt cache confidence
the reference port, as it was before its logic moved (Unity 6000.3) 90,777 4,888 6.5 billion (5.0 billion to 8.4 billion) 176 million $2,705 ($2,078 to $3,467) $26,680 LOW
a second game, another studio's (Unity 2021.3), every folder its project file names 125,959 56,170 10.0 billion (7.9 billion to 12.6 billion) 263 million $4,089 ($3,231 to $5,130) $40,898 LOW
the same game, its two vendored libraries excluded (a networking framework and a WebSocket client, each read by its namespace) 89,817 13,840 6.6 billion (5.1 billion to 8.4 billion) 178 million $2,738 ($2,119 to $3,488) $27,105 LOW

How big each project is, read off its files by the same census (a code line has its comments and strings blanked, and blank lines are not counted):

  • The reference port, as it was before its logic moved (Unity 6000.3): 95,665 code lines of game C# in 339 files (90,777 coupled, 4,888 pure); its own editor tools 111,014 lines in 282 files, not ported; 3,768 prefabs, 2,445 of them with a particle system; 146 scenes, 1 in the build.
  • A second game, another studio's (Unity 2021.3), every folder its project file names: 182,129 code lines of game C# in 1,932 files (125,959 coupled, 56,170 pure); its own editor tools 7,366 lines in 55 files, not ported; 3,229 prefabs, 52 of them with a particle system; 463 scenes, 24 in the build.
  • The same game, its two vendored libraries excluded (a networking framework and a WebSocket client, each read by its namespace): 103,657 code lines of game C# in 1,392 files (89,817 coupled, 13,840 pure); its own editor tools 5,333 lines in 30 files, not ported; 3,229 prefabs, 52 of them with a particle system; 463 scenes, 24 in the build; 80,505 lines of vendored libraries left out.

The rates they multiply by, each read from the reference port's records (u2ue/basis/tokens.json):

  • logic_coupled_line: 70,776 tokens per coupled code line, n=27, bootstrap band 54,112 to 91,003, one sample's actual over predicted 0.40 to 2.13 (leave-one-out, P10 to P90), all-in overhead x1.61 (all the agents of wf_341e7e76-b72 over those that moved one measured file each: verifying, gating, playing and consolidating are real cost too); 97.3 % of them cache reads, 0.6 % output. Workflow runs wf_341e7e76-b72 (81 agents): each step agent's tokens off its own transcript; each step's file measured in the pre-move copy (14469 code lines in 27 samples).
  • logic_pure_line: 19,358 tokens per pure code line, n=1, all-in overhead x1.61 (all the agents of wf_341e7e76-b72 over those that moved one measured file each: verifying, gating, playing and consolidating are real cost too); 98.0 % of them cache reads, 0.4 % output. The pure batch step of wf_341e7e76-b72: 5 moved files, 2751 code lines in the pre-move copy.
  • conductor_turn: 563,904 tokens per model call, n=13, bootstrap band 502,050 to 568,133, one sample's actual over predicted 0.25 to 0.97 (leave-one-out, P10 to P90); 99.2 % of them cache reads, 0.2 % output. 13 main-session transcripts on claude-opus-5-5 since 2026-10-01 (49148 calls), one call = one turn.

Opus 5.5's list price per million tokens: input $4, cache write $5 (5 minutes) or $8 (1 hour), cache read $0.20, output $20 - read 2026-10-17 from https://platform.claude.com/docs/en/about-claude/pricing.

  • saving effect_prefab: ABSENT - the reference port's effects were ported in main sessions and the lane's queues, not in workflow runs that count prefabs: the three effect workflow runs there are were method work, with no count of prefabs ported
  • saving scene: 859,736,921 processed tokens per scene by hand, $294 at Opus 5.5's list price (15 million new), n=1: 8 workflow runs (wf_8bb82424-fb6, wf_9e5fde94-0ab, wf_a9670ab9-cdb, wf_baf92932-d44, wf_5f097467-aa1, wf_9f5af880-73d, wf_32e26135-528, wf_3aa4fd19-2ad): every agent's transcript

A yardstick. The reference port, the game the toolkit was built on and its first row, is a medium-sized game: about 96,000 code lines of game C#, thousands of prefabs and over a hundred scenes (its size line above). Bigger than a game jam project, well short of a large studio title. The logic estimate grows with the coupled lines, so a game with half as many coupled lines costs about half as much to port.

What the number is made of

The logic is where the tokens go. Effects, scenes, UI conversion, the game's own Unreal project, parity and the acceptance page (the report of every effect, every gap and every decision left to the game's owner) are each run by a verb. u2ue port runs them and stops only where a person, the AI or a Unity editor is needed. Each stop costs one turn of the model, priced at the measured tokens per call (conductor_turn in the block above; Chapter 4 has the stops). The logic is the one part an AI writes: it moves the game's rules out of its MonoBehaviours into an engine-free model (Chapter 5, and the logic skill).

The logic's rate was measured, not modelled. The reference port moved its coupled files into an engine-free model with one agent (an AI model session given one task) per file. Each agent's tokens are read off its own transcript, with a streamed call counted once. Each file is measured in a copy of the project taken before the move, by the same classifier the estimate applies to your project. Agents that verified, gated or played the game, rather than moving one measurable file, are in the rate as overhead, so it is all-in.

Processed tokens and new tokens are different things. Every call reads its whole context again, and processed tokens count every token a call reads or writes. Claude Code (the Anthropic tool the model works in) serves most of that from the prompt cache, and a cache read costs a twentieth of an uncached input token on Opus 5.5. So most of the processed tokens are cache reads, and they cost little. That is why a total in the billions costs thousands of dollars, not tens of thousands. The column "with no prompt cache" shows the difference. The new tokens (the column "of them new") are the rest: uncached input, cache writes and output.

The prices are read, not remembered. They come from Anthropic's pricing page and are kept with the date they were read (u2ue/basis/prices.json). They are the API's list price on the standard tier. A subscription plan's usage limits are not modelled.

How sure it is

The confidence is printed for every stage, with its reasons, and every estimate above reads LOW. The number of samples, the model a rate was measured on and how far a game lies outside the measured files set it; four things to know:

  • Per file the estimate is rough; summed over a game it is steadier. The leave-one-out figure in the block above is how far one file's real cost fell from what the other files predicted for it; P10 to P90 is the range that holds the middle eight files in ten. Over many files those errors average out, which is what the bootstrap band shows: the rate recomputed over many random resamplings of the measured files, from its P10 to its P90.
  • The logic rates were measured on Opus 5 and Fable 5.1 (two other Claude models), and priced as Opus 5.5. Opus 5.5's own token count for the same work is unmeasured.
  • A game much larger than the measured files is an extrapolation. The tool prints how many times larger.
  • The pure-code rate rests on one sample, and the main session that ran the extraction (the conversation that directed its agents) is not in the logic rate, so for that part the figure is a floor.

To raise the confidence, measure your own game: port one slice with the skills, then rebuild the basis from your own runs (py u2ue/survey/token_basis.py --project <game> --write, which reads your project file's estimate_basis block). The estimate then speaks for your game and your model.

What the toolkit saves

  • Prompt caching. The block above prices the same calls with and without the cache. This is measured on the work the rates come from.
  • The stages a verb runs. The reference port brought its first level to Unreal by hand, across eight agent runs; the saving line in the block gives what that cost. A verb now runs that path (Chapter 6). The saving is claimed for one scene only, because what a second scene costs by hand was never measured.
  • Effects. No saving is claimed. The reference port's effect work was not done in runs that count prefabs, so there is no rate to claim from.
  • The logic. No saving is claimed. It is AI work with the toolkit or without it, and no port was measured without the toolkit. What the toolkit adds there is a check on every step: the gates and parity that make the model's work provable (Chapter 14, Chapter 15).

How long it takes

The estimate does not give a time, because no time per line has been measured yet. For scale: the reference port's extraction ran as one workflow (a script that runs many agents and decides what runs next) of 81 agents, and its record shows it ran for close to sixteen hours. A single session stops long before that. Chapter 15 explains how the long-run skill and a workflow keep a port going.

Porting to Unreal in a nutshell

Who this is for: the evaluator who wants the whole job on two screens before deciding - a quick start to try on your own project today, and the five problems every Unity to Unreal port meets, each with the toolkit's answer and the chapter that has the details.

Quick start

You need Windows with native PowerShell, Python with PyYAML, the .NET SDK, Unreal Engine 5.7, and your Unity project saved as text (Force Text serialization). Chapter 3 has the full list.

py -m u2ue                                          # every verb the toolkit has
py -m u2ue find <words>                             # everything it holds about a subject, as path:line

First, what it will cost. This needs no project file:

py -m u2ue estimate --unity <your Unity project> --roots <the game's code folders>

Then describe your game in one project file, u2ue/projects/<game>.json (Chapter 3 has a complete one), and run the port:

py -m u2ue --project <game> port                    # every stage, read from its records, and the next action - nothing runs
py -m u2ue --project <game> port --run              # runs every stage a verb can; stops where a person, the AI or an editor is needed

port stops in four places: the project file, which only you can write; the logic, which the u2ue-logic skill does in Claude Code with u2ue-long-run keeping the session going (Chapter 15); a Unity window, for what can only be measured or captured in your editor; and the decisions the acceptance page asks of the game's owner. Run port again after each stop: it reads where the port stands. Chapter 4 walks the stages one by one with real output, and What a port costs says what the estimate is made of and how sure it is.

The five problems every port meets

1. Unity does not behave the way its documentation reads

A converter written from the documentation is wrong in the details that show: the frame a sub-emitter's child (a particle system its parent's particles start) is born on, what a scaling mode really scales, how Mono prints a float. The toolkit measures Unity instead of reading about it. A probe case is data, run in the game's own Unity editor only while the person using it is idle, and judged by a judge that must refuse a planted wrong answer. Each rule is stored with the Unity version it was measured on, and on another version it is reported as unverified rather than trusted. Chapter 8, Chapter 12.

2. Shuriken and Niagara do not map one to one

Shuriken is a fixed set of modules; a Niagara emitter is a set of scripts, each a stack of modules (Chapter 11). A Unity setting can need several Niagara modules, and some have no equivalent at all. The toolkit reads every effect into an engine-neutral IR (an intermediate representation: one JSON file per effect, read from Unity's YAML), converts it in stages, and puts each behaviour it adds behind a switch. A switch starts OFF and is turned ON only with an evidence row that a trial proved. What cannot be ported is named per emitter on the acceptance page, never dropped. Chapter 7, Chapter 11.

3. The game's rules are tangled into MonoBehaviours

The rules live inside Update methods, coroutines, inspector values and Unity types, in an execution order nobody wrote down. The toolkit moves them into an engine-free model behind seams. The engine fills the seams (view, input, camera, effects, platform); the model is driven in Unity's frame order and runs without either engine. Its answers are proven by float bits on .NET, on that Unity version's own Mono runtime, and in Unreal. Chapter 5, Chapter 14, and the logic skill.

4. Transforms do not compose the same way

The two engines differ in axes, units and rotation order. Worse, a non-uniform scale under a rotation makes Unity draw a shear that Unreal's transform cannot hold at all. The toolkit states one conversion, in one place, and finds every node Unreal cannot place as Unity does (py -m u2ue --project <game> shear), with the error in centimetres. Such a node is named for a decision, never averaged into something that looks close. Chapter 6.

5. "It looks right" is not proof

A photo of an effect is one draw of a random process. A metric alone can lie too: on the reference port, a render whose whole scene went black scored better, because dark geometry stopped hiding a bright backdrop. The toolkit proves the data first. It reads back every emitter frame by frame and holds it to Unity's own particle state (u2ue conform). It reports "identical" as a family of four numbers, never one. Pictures come last, with the capture's own artefacts labelled. Chapter 9, Chapter 10, Chapter 14.

The one rule under all five

Every value is READ from the source, with where it came from; or MEASURED in Unity, by a judge that can fail; or ABSENT, named with the reason. There is no fourth kind. A port that guesses looks finished long before it is. Chapter 1.

The short version

Who this is for: the evaluator who wants every aspect of a port in one sitting - one screen each, saying what happens, the command that does it, what it printed on a real game, and what it does not do yet.

The output shown here is real, from a second Unity game the toolkit was not built on (Unity 2021.3, a different studio's project), with that game's name written <game> and machine paths written <work>/... and <unreal project>. Numbers from the game the toolkit was built on - a commercial Unity 6 tactics game ported to Unreal Engine 5.7 - are called the reference port. Part II has the procedure behind each screen, and Appendix B the plan for each NOT YET.

S1. What u2ue is, in five lines

  1. A command-line facade, py -m u2ue, over the tools that move a Unity game to Unreal Engine 5.
  2. It reads the Unity project as text (YAML prefabs, scenes, materials, .meta files): no Unity editor runs to port anything.
  3. It converts what has a counterpart (particle effects, transforms, UI layout, lights, materials), and gives the game's own code a runtime and a method instead of pretending to translate it.
  4. Where Unity's behaviour is not written down, it measures Unity, once, in the game's own editor, and keeps the measurement.
  5. It proves every change before it ships and reports every difference by name, with a number and a reason.

It is not a button that makes a Unity game run in Unreal. Chapter 1 says exactly what it does and does not promise.

S2. The workflow at a glance

The default path is two commands: py -m u2ue estimate --unity <unity project> for the price, then py -m u2ue --project <game> port and port --run, which run every stage below that a verb can do and stop where a person, the AI or a Unity editor is needed (Chapter 4). The stages:

flowchart LR
  P["describe the game<br/>info"] --> C["the code<br/>inventory, data"]
  C --> X["the content<br/>extract, check"]
  X --> B["Unreal<br/>build, read, photo"]
  B --> R["the result<br/>report, metrics"]
  M["measure Unity<br/>probe + judge"] -.-> X
  M -.-> B
step command runs in
say where everything is py -m u2ue --project <game> info no editor
list the game's code and what it touches inventory no editor
read what the inspector holds data --from <asset> --script <Class> no editor
turn the effects into an engine-neutral IR extract no editor
run every selftest and gate check no editor
build, read back, photograph build, read, photo Unreal, headless
the acceptance page and the numbers report, metrics, tempo no editor
search everything the toolkit knows py -m u2ue find <words> no project

S3. Describe the game

What happens. One JSON file per game, u2ue/projects/<game>.json, names the Unity tree and version, the Unreal host, where the work goes and the game's folders. No field is defaulted: a missing one is an error, not a guess.

py -m u2ue --project <game> info
project <game> (u2ue/projects/<game>.json)
  unity.root           dir       <unity project>                     ok
  unity.assets         dir       <unity project>/Assets              ok
  work.effects         out-dir   <work>                              ok (exists)
  work.photos          out-dir   <work>/photos                       to be created (its parent exists)
  unreal.uproject      file      <unreal project>.uproject           ok
  unreal.content_root  game-path /Game/U2UE/<Game>                    ok (an Unreal content path)
  unity.editor         dir       <Unity 2021.3.21f1 install>         ok (its unity_builtin_extra exists)
  adapter: unity_project (spawn rules unity)

Every path is opened, not just printed. The last line names the game's adapter: the object that answers the few questions that differ per game, such as which prefabs are effects (Chapter 18). Limits: the project must be serialized as text (Unity's Force Text).

S4. The game's code

What happens. The toolkit does not translate MonoBehaviours into Actors. It tells you what every type touches, and gives you a method: move the rules into an engine-free model (plain C# that references no engine), let each engine run it through a thin host, and prove both engines get the same answers.

py -m u2ue --project <game> inventory
u2ue inventory <game>: 1987 files, 2453 types (plain 1384, MonoBehaviour 789, ScriptableObject 160, ...); 1148 pure rules
  serialized data                  473 types   1708 sites
  platform (log, files, prefs)     365 types   1525 sites
  spawn / destroy                  311 types   1049 sites
  lookups                          275 types    661 sites
  coroutines / Invoke              273 types    997 sites
  transform                        222 types   1652 sites
  ...

The 1148 pure rules use no Unity API and move first. The inventory also lists every MonoBehaviour's script execution order with its lifecycle methods - the table Unity's frame is rebuilt from. Then:

need what the toolkit gives
inspector values, ScriptableObjects u2ue data: every serialized value, prefab overrides applied, references resolved to asset paths
Unity's frame, Time.deltaTime, coroutines the U2ue.Runtime .NET library: UnityFrame, UnityClock, Coroutines with Unity's rules, each held by tests
logging, files, PlayerPrefs, JSON, random six platform interfaces with Unity's exact semantics (Random.Range's bounds, JsonUtility's fields)
an Unreal host to start from the U2ue.Unreal templates: the frame actor, the pointer, the camera rig, the platform services
the model stays engine-free u2ue check --only model: an engine reference in the model fails
the answers agree u2ue parity: every runtime's digest (its answers to the same cases, floats written as bits) compared float bit by float bit

Limits: the toolkit does not move the code or write the hosts. Chapter 5 is the method. Measured on the reference port: three scripted battles gave byte-identical event logs in the Unity-free test run and in the Unreal host.

S5. Transforms, hierarchies and scenes

What happens. Unity is metres, y up, left handed; Unreal is centimetres, z up, left handed. One module holds the conversion, and its selftest holds it to the two other copies in use, the effect converter's and the reference port's model's, so they cannot drift apart unseen (Chapter 6 has the table).

The one thing that does not convert: a rotated child under a non-uniformly scaled parent is sheared in Unity, and Unreal's transform cannot hold a shear. u2ue shear finds every such node and says how far off it would land, in centimetres:

py -m u2ue --project <game> shear --from Assets/<Scene>.unity

Expect some: measured on the reference port's first battle map, 46 nodes were sheared, two of them drawn, the worst 63 cm off. Accepting, baking or fixing each is your decision, made with the number.

Whole scenes go through u2ue scene: export to glTF (an open 3D scene format) in the game's own editor, import into a new Unreal level, read the saved level back, and scene check - a gate that grades hierarchy, materials, textures, lighting and placement against the scene's own measured baseline. Limits: the steps between import and readback (textures, material parents, lighting, outline hulls) are tools, not verbs yet: Chapter 6 lists them, and Appendix B has the plan.

S6. Prefabs, and reading Unity's YAML

What happens. Effects and data are read straight from the YAML: nested prefab instances expanded with their modifications, prefab variants, removed components, the material chain through m_Parent. Each effect is counted as a key: one effect the game can spawn, usually one prefab. A file the reader cannot handle is refused by name, never half-read:

py -m u2ue --project <game> extract
u2ue extract: 60 READ key(s): 56 IR file(s) with 189 emitter(s), 4 refused by name, 0 dropped, 0 foreign path(s)
  REFUSED unity.prefab.5ccd...: .../Winter Door.prefab: PrefabInstance 4843689442982340616: modification target 1211823196678298638 (m...

Limits: a prefab instance's removed components and removed GameObjects are applied, but one that adds a GameObject or a component to its source is refused by name; objects inside a nested model (FBX) are not read - FBX is binary - so a scene that modifies one is refused by name.

S7. Materials and lighting

What happens. Effect materials use custom shaders. The blend mode is read as a number from the material (_DstBlend == 1 is additive), never from the shader's name. Each shader family gets one Unreal parent material, authored once; every material of that family becomes an instance with its values read off its .mat.

Lit materials need Unity's lighting, not Unreal's. For Shader Graph materials the toolkit translates the HLSL Unity itself generated for the graph, and evaluates URP's own Lit lighting (URP is Unity's Universal Render Pipeline; the lighting is its BRDF, its spherical-harmonics ambient, its reflection decode) from the scene's measured sun, ambient probe and reflection cube.

Point lights an effect carries become Unreal point lights by a mapping read from both engines' source (Chapter 7 has it). In Unity the mapping's source side was measured on lit pixels: nine cases fit URP's own formula at a ratio of 1.0000.

Limits: the lit route is behind a switch until its trial is looked at; a graph that moves vertices in object space, or that includes custom code, is refused by name; fog, shadows and ambient occlusion on these materials are named, not drawn.

S8. Particle effects

What happens. Every Shuriken ParticleSystem becomes a Niagara emitter, written through Unreal's own converter library, in twenty stages in the order Unity runs its modules. Each Unity behaviour added to the converter is a route: it arrived behind a switch, default off, and was flipped on only with its evidence.

An emitter Unreal does not draw is a gap only if Unity draws it. What u2ue metrics prints about it (the reference port, from its record of 2026-10-15, lines shortened):

keys      674: BUILT 673, IR REFUSED 1; 673 drawn, 197 of them with a named gap
emitters  drawn 7810 | absent: gap 642 (Unity draws them, Unreal does not), 374 absent exactly as in Unity
coverage  92.4 % of the emitters Unity draws are drawn in Unreal (7810 / 8452)

Limits: VFX Graph assets and particle systems authored directly in scenes are listed, not converted. TrailRenderers: Unity's law is measured and reproduced exactly by U2ue.Runtime.TrailLaw; drawing it in Unreal is NOT YET (Appendix B has the plan). Chapter 7 has the rest.

S9. UI

What happens. uGUI (Unity's UI system) and UMG (Unreal's) lay out differently, so the toolkit does not rebuild screens as UMG trees. A Unity Canvas is captured (every RectTransform, anchor and component, as Unity resolved it) and laid out in Unreal by a port of uGUI's own layout solver and TextMeshPro's glyph layout, the generic library U2ue.Ui:

py -m u2ue --project <game> ui test
py -m u2ue --project <game> ui convert <capture> --screen NAME --out DIR

The tests hold the library to Unity's own captures, and a planted transform defect makes them fail (Chapter 6 has the run). Limits: the capture runs in the game's Unity editor in Play mode; shipping it as the package's Editor assembly is NOT YET (Appendix B), so ui capture refuses by name until then. Which view model feeds which panel stays the game's.

S10. Audio

What happens. Authored clips (.wav, .ogg) import into Unreal as Sound Waves. Which sound plays, and how loud, should be a rule in the model, so both engines choose the same one. Sounds Unity generates at run time are rendered once to float PCM and played through a small bridge that hands the samples to Unreal's mixer unconverted. Limits: the bridge is the host template's plugin; it builds in a host and plays headless (its judge passed the captured tone on 2026-10-15). Mapping a Unity AudioSource is NOT YET (Appendix B).

S11. Measuring Unity

What happens. Much of what a port must match is not documented: the frame a sub-emitter's particle is born in, how a trail drops its points, what a Timeline does before its clip starts. The toolkit measures it:

  1. A judge (Python) states the rule and is selftested against planted wrong answers - before any measurement exists.
  2. A probe (an Editor C# script) is dropped into the game's editor in a window: only after ten idle minutes, stopped the moment its user returns, compiled headless first, everything else's checksum compared before and after.
  3. The probe writes a bake; the judge reads the rule off it or refuses it with the numbers.

On the second game, on 2026-10-17:

py -m u2ue --project <game> check --only facts
  188 measured Unity bakes; this project is Unity 2021.3.21f1
       188 measured on Unity 6000.3.16f1    UNVERIFIED for Unity 2021.3 - re-measure where it matters
  188 of 188 rules this project's build uses were measured on another Unity: its report must not call them measured for it

A rule measured on another Unity version is still used, but never reported as measured for this game.

S12. Proving every change

What happens. Four rules, each enforced by a gate rather than recommended:

  • Read it or name it absent - no plausible default stands in for a value.
  • A gate must be able to fail - every gate carries plants it must refuse.
  • Prove a change offline - the converter is replayed against a recording stub (a stand-in for Unreal that records every call the converter makes, in order) over every emitter of every effect: switched off, a new route must change nothing; switched on, exactly the emitters it names.
  • Verify with both - the data proves itself first; then the numbers and the pictures confirm it, each looked at.
py -m u2ue --project <game> check            # every selftest, the field gates, the measured rules' versions, the model gates
py vfxport/whole_trace.py REF.py WORK.py     # a converter change: identical engine calls, or exactly the predicted set

S13. Reports and numbers

What happens. Every number comes from a record on disk, with its denominator, its definition and its date; a number that cannot be computed prints ABSENT with the record it needs; an input older than the newest build prints STALE.

py -m u2ue --project <game> report --out <game>.html      # the acceptance page: every key, every gap, every owner decision
py -m u2ue --project <game> metrics                       # coverage, measured share, read-back, photos, machine hours, routes
py -m u2ue --project <game> tempo                         # each route's first code -> verified flip, read off git

Before anything is built, the page already lists every effect the game must account for.

S14. What it does not do

  • Animation (Animator state machines, Mecanim retargeting) and physics: not covered. The reference port had neither, so no tool is claimed until a game that has them is ported and measured. One animation case is handled: an Animator that drives an effect root's scale.
  • The game's code is moved by you or by an AI model following the logic skill, with the method, the runtime and the gates (S4).
  • Anything the toolkit cannot reproduce exactly is reported on the item, with the measured size of the difference.

1. Introduction

Who this is for: the evaluator - exactly what u2ue is, what it does today, the rules it holds itself to, whom it serves and what it does not promise. It is the last page of Part I: after it you can decide, and the porting developer moves on to Part II.

What u2ue is

u2ue is a set of tools behind one facade, py -m u2ue, for porting a Unity game to Unreal Engine 5. Every tool in it was written while moving one real game - the reference port, a Unity 6 tactics game - to Unreal 5.7, and u2ue check runs the tools' selftests (Chapter 21 lists them). A second, unrelated game (a different studio's project on Unity 2021.3) runs through the same facade to keep the toolkit honest about what is general and what was one game's.

A port with u2ue has two halves:

  • The game's code. The toolkit inventories the game's C# type by type, reads its serialized data, gives the moved code a runtime that keeps Unity's frame, time and coroutine rules, gates the result so it stays engine-free, and compares its answers across the runtimes it runs on (Chapter 5).
  • The game's content. Particle effects are converted end to end - read from the prefabs, converted to Niagara, built headless, read back frame by frame, photographed beside Unity's frames, and reported (Chapter 7). Transforms, scenes, UI and audio have their own tools and methods (Chapter 6).

For the effects, the job fits in one line: every Shuriken particle effect a Unity game fires becomes a Niagara system in Unreal that draws as Unity draws it - and every place it does not is named, on the emitter, with the reason.

The problem it solves

In one sentence: a studio engineer, helped by an AI agent, uses one package with a single entry point to port a whole Unity game to Unreal - its MonoBehaviour code, its transform chain and scenes, its effects and the rest - by implementing adapters or interfaces rather than making the game generic, with an architecture a senior engineer can grasp, and with the porting speed and the percent identical measured.

The problems that fall out of that sentence are the toolkit's shape:

problem where the toolkit answers it
knowing what the toolkit already holds py -m u2ue find (Chapter 2)
knowing what a game's code needs before porting it u2ue inventory (Chapter 5)
moving game code without making the game generic the engine-free model and its adapters (Chapters 5 and 18)
the transform chain u2ue.transform, u2ue shear (Chapter 6)
proving how identical the result is parity, read-back, photos and the metrics (Chapters 5, 9 and 10)
a review that holds the use cases and the class model (Chapters 17 and 22)

What it does today

area today
The price of a port, before it starts HAVE - u2ue estimate, from rates measured on a real port (What a port costs)
The whole port as one command HAVE - u2ue port, which runs every stage a verb can and stops where a person, the AI or a Unity editor is needed (Chapter 4)
Shuriken particle effects to Niagara HAVE - extract, check, build, read, photo, report, metrics (Chapter 7)
Effect materials (custom shader families) HAVE - one parent per family, every material an instance read off its .mat (Chapter 7)
Lit (Shader Graph / URP Lit) effect materials HAVE behind a switch, default OFF until its trial's photos are looked at - the graph's generated HLSL translated, URP's lighting evaluated (Chapter 7, Appendix B)
Point lights on effects HAVE - read, mapped by both engines' source, spawned on the effect; the Unity side measured on lit pixels (Chapter 7)
Code inventory and frame order HAVE - u2ue inventory (Chapter 5)
Serialized data (inspector values, ScriptableObjects) HAVE - u2ue data (Chapter 5)
Unity's frame, time, coroutines, platform services HAVE - the U2ue.Runtime .NET library (Chapter 5)
Engine-free model gates HAVE - u2ue check --only model (Chapter 5)
Cross-runtime parity of the game's rules HAVE - u2ue parity; Unity's side run on its own Mono with no editor by u2ue digest (Chapter 5, Chapter 14)
Unreal host templates (frame, pointer, camera, platform) HAVE - U2ue.Unreal, compiled against UnrealSharp; a headless smoke run is NOT YET (Chapter 5, Appendix B)
The game's own Unreal project HAVE - u2ue host, step by step, each step judged by its proof line (Chapter 3, Chapter 13)
Effects held to Unity on numbers HAVE - u2ue conform: Unity's particle state against Niagara's read-back, every emitter (Chapter 9)
Transform conventions, shear HAVE - u2ue.transform, u2ue shear (Chapter 6)
UI layout (uGUI, TextMeshPro) HAVE - the U2ue.Ui library and u2ue ui convert; the capture as a package Editor assembly is NOT YET (Chapter 6, Appendix B)
Measuring a Unity behaviour HAVE - the probe / judge / window protocol (Chapter 8)
TrailRenderers HAVE the law (U2ue.Runtime.TrailLaw, exact against Unity); drawing it in Unreal is NOT YET (Appendix B)
Scene export / import / readback / fidelity HAVE - u2ue scene; the steps between import and readback (textures, material parents, lighting) are tools, NOT YET verbs (Chapter 6, Appendix B)
Audio HAVE the method and the PCM bridge plugin, which builds in a host and plays headless (judged 2026-10-15); mapping a Unity AudioSource with no human step is NOT YET (Chapter 6, Chapter 13, Appendix B)
Animation, physics NOT YET - not covered; no tool is claimed until a game that has them is ported (Appendix B)

Three principles

Every stage follows three rules. Each was earned by a failure, and the toolkit enforces them rather than recommending them.

  1. Read it, or name it absent. A value the port writes is read from the Unity source; one it cannot read is named absent with the reason. There are no defaults that stand in silently: a substituted value is a lie the acceptance report would repeat.
  2. Every rule is measured. How Unity behaves is read from its data, its source where it ships source (Unity's packages, Unreal's engine), or measured in Unity by a probe whose judge is written first and refuses a planted wrong answer. A rule measured on one Unity version is reported as unverified on another (Chapter 8).
  3. Every change is proven before it ships. A new converter route lands behind a switch, default off; the converter is replayed over every emitter of every effect and must show identical engine calls except exactly the predicted set; a trial is built, read, judged and photographed; only then does the default flip (Chapter 9).

In practice: a measured rule's bake is kept as a fact file (shared/conformance/*-facts.json) with the Unity version it was measured on, and a project on another version is told which rules are unverified for it (u2ue check --only facts). Documentation and intuition are where a rule is suspected, never where it comes from. The replay that proves a converter change, whole_trace.py, traces every engine call of every active emitter of every effect, under one converter file and then the other, and compares them.

Who it is for

  • An evaluator deciding whether to use it: Part I of this manual.
  • A porting developer - an engineer moving a Unity game to Unreal, who wants the game running the same and every difference named: Part II.
  • An AI model doing that port: the package ships skills for it (the entry skill u2ue/skill/u2ue/SKILL.md, which hands the game's logic to u2ue/skill/u2ue-logic/SKILL.md and an effect gap to u2ue/skill/u2ue-port/SKILL.md), and every output is text a model can read (Chapter 15).
  • A toolkit developer extending it, and a reviewer - a senior engineer judging how a port is done: Part III. Chapter 22 and u2ue/ARCHITECTURE.md are written for the reviewer.
  • The game's owner - who answers only the decisions that are theirs; the report lists them, each with its count.

Two systems support them: the game's Unity editor, where a Unity behaviour is measured only while the person using it is idle (Chapter 8), and the Unreal host, where one headless Unreal runs at a time (Chapter 3).

What it does not promise

u2ue does not make a Unity game run on Unreal by itself. The game's own code has to be moved into an engine-free model and given Unreal hosts, by an AI model following the logic skill or by a person - the toolkit gives the method, the runtime, the analysis and the gates, not a button. Where it cannot reproduce Unity exactly, it says so on the item, with the measured size of the difference. Appendix B lists what is not done yet.

u2ue as a product

u2ue is built to ship as a Unity package installed in the source project, which an AI model drives through the same command line a person uses (Appendix B has the package's layout and what is left to ship). How identical the result is, is measured, not claimed; so is how long each converter route took from its first code to its verified flip. How fast a whole game is ported is not measured yet (Chapter 10).

What is reusable, in five layers

The tools fall into five layers. The first three are the product and serve any game; the fourth serves any game that uses the same vendor effect packs (third-party sets of ready-made effects and their shaders); the fifth is each game's own. Not every tool reads its paths from the project file yet: a tool that still names one game's folder is converted by the recipe in Chapter 18, and Appendix B tracks the rest.

  • Unity readers, offline (no editor). Prefabs, nested, variant and legacy, read into the engine-neutral IR; Unity's own imported textures read off Library/Artifacts, every mip it samples; its built-in resources; alpha derivations; a PSD inside a PNG. Proven on two games and two Unity versions.
  • The engine-pair knowledge: Shuriken to Niagara. Every route flipped on with its evidence row, or named OFF with what it waits on; Chapter 21 counts them. Every rule in it was MEASURED in Unity or READ in an engine's source. This is the asset a second game reuses for free.
  • The proof machinery. The read-back per frame and its sweep (each check run over every emitter read back), a judge per route written before its trial with a plant that must fail, photo pairs against Unity's fixed-seed reference frames, sheets that label the capture's own artefacts, the acceptance report, and u2ue metrics.
  • Asset-pack material ports. One hand-authored Unreal parent per Unity shader of the vendor effect packs the reference port used (Chapter 18 lists them) - reusable by any game that uses those packs.
  • The game's own. Its engine-free model (the method of Chapter 5 is reusable; the code is not), its effect maps, its scenes.

2. Concepts

Who this is for: the developer porting their own game - the ideas the rest of Part II is built on (the project file, the facade, adapters, asset families, the IR, routes and switches, windows, gates, the model and the concept classes), each explained once, so no later chapter stops you on a word.

The project

A project is one JSON file, u2ue/projects/<name>.json, that names everything about one game: its Unity tree and version, its Unreal host (the Unreal project the toolkit builds and runs in), where the work goes, and the game-specific choices. A required field that is missing is an error, never a default. Chapter 3 lists the fields; py -m u2ue --project <name> info opens every path the file names.

The facade and its verbs

The facade, py -m u2ue, is the only entry point. It answers verbs (its commands) such as estimate, port, info, inventory, extract, build and parity; py -m u2ue alone lists every verb, and Chapter 20 documents each one. A verb WRAPS the tools that do the work and never rewrites them, so every tool still runs by hand, with its own selftest where it has one (the tool's check of itself, which must refuse a planted fault).

py -m u2ue find <words> searches everything the toolkit holds (concepts, verbs, adapters (below), tools, every documentation section, measured rules, converter stages, verified routes) and needs no project. Every word must match; the hits come grouped by kind, best first, each with the file:line to open next (--kind narrows the kinds, --top N shows more of each):

py -m u2ue find coroutine

Adapters: where a game plugs in

The toolkit holds no game's knowledge. The few questions whose answer depends on the game are ports (u2ue/adapters/__init__.py; here a port is a question the toolkit asks and the game answers, not the act of porting), answered by an adapter:

port the question the default (any Unity project) a game adapter (example: the reference port's)
effect_keys which prefabs are the game's effects every prefab holding a ParticleSystem the keys its battles actually fire, resolved as the game resolves them
spawn_rules what starts when the game spawns one Unity's: playOnAwake systems and their sub-emitters its effect pool's own rule
host_busy is the Unreal host free no Unreal is running and none of its own build queues is alive

Most games need no adapter of their own: the project file (u2ue/projects/<name>.json) says "adapter": "unity_project". The default adapter was proven on a second game: 60 effect keys (an effect key is one effect the game can spawn, usually one prefab), 56 IR files (the IR, below, is the form each effect is read into), 189 emitters, 4 refused by name, 0 dropped, with no game code written (Chapter 4, step 5). A game adapter subclasses UnityProject and overrides only the answers its game gets wrong (Chapter 18). extract refuses a resolve (the key list the adapter writes) whose keys disagree with the adapter's spawn rule, because the IR reader picks the rule by the key.

Asset families: what ports itself

Everything except a game's logic ports with no AI in the loop. Each kind of asset is an asset family, and every family takes the same five steps: extract it from Unity, build it in Unreal, read back what Unreal built, judge that against Unity, and photograph it. A step no command does yet is ABSENT and says why. The table is generated from u2ue/assetfamily.py and checked against the facade, so every command in it exists:

family extract build read judge photo
effects extract build read conform diff photo
scene scene export scene import scene readback scene check ABSENT
ui ui capture ui convert ABSENT ui test ABSENT

Each command runs as py -m u2ue --project <name> <command>. Where a step is ABSENT:

  • scene photo: no verb photographs a level: the scene check judges data only (hierarchy, materials, textures, lighting, placement)
  • ui read: no separate read: the converted screen is laid out headless inside ui test, the same run that judges it
  • ui photo: no verb photographs a screen

The engine-neutral IR

Effects pass through an intermediate representation: one JSON file per effect, read off the Unity YAML by u1e_ir.py (nested prefab instances expanded, overrides applied, every node's frame composed). The IR is the boundary between the engines: it is testable without either editor and diffable between runs.

The converter, its routes and switches

vfxport/build_niagara.py turns one IR emitter into Niagara stack writes, in twenty stages in the order Unity's own modules run. A route is one ported behaviour (a shape, a curve mode, a sub-emitter trigger). Each new route lands behind a switch (an environment variable, VFXPORT_<NAME>), default off, and is flipped on only after its proof (Chapter 9). Chapter 21 lists every switch, its default and its evidence.

Windows: measuring Unity

Where Unity's behaviour is not in its data, it is measured. A probe (a small Editor script) is dropped into the game's Unity editor for one run inside a window - only after ten minutes with no mouse or key input from its user, and stopped at its next step once they return - and writes a bake: raw numbers only. A judge (Python), written and selftested before the bake exists, decides what the numbers say and refuses a planted wrong answer. The bake is kept with the Unity version it was measured on (Chapter 8).

Records, reports and gates

Every build, read and photo writes a record. The acceptance page (every effect key, every gap and every decision the owner owes, written by report) and the metrics are computed from records only, each number with its definition and age. Gates refuse what must not pass: field gates (an unread Unity field is a silent gap), model gates (the code moved into the model, below, must know no engine), the converter trace (a change must touch only what it predicts), parity (the rules must agree across runtimes).

The model architecture (the game's code)

The game's rules move into an engine-free model (plain C#) behind two kinds of seam - a platform seam (logging, files, preferences, JSON, random numbers) and view seams (what the presentation asks the engine to draw) - and each engine gets one thin host (that engine's code that runs the model; not the Unreal host project above). Unity and Unreal then run the same model, which is what makes parity provable. Chapter 5 is the method.

The concept model: one class per idea

Every idea you need to follow a port is ONE class in the toolkit, with a docstring that says what it is and where its evidence lives. The product in one sentence: you point an AI agent at a Unity game; the agent ports the game's LOGIC through the u2ue-logic skill (Chapter 5), and every other asset family ports itself - each by Routes that follow measured Rules, held to Unity by Judges. py u2ue/survey/concepts_gate.py checks every concept the table below names, and a pillar (one promise of the product) of u2ue cycle requires the count that exist never to go down. The concept diagram is generated from u2ue/CONCEPTS.md: Chapter 22, "The concept model".

Where each concept lives in the code

Every concept is a class today (the source table's status column reads EXISTS on every row). The class column is the module and the class that holds it.

concept class where it lives, and what it does
Project u2ue/project.py:Project the project file and the environment it exports
Adapter u2ue/adapters/__init__.py:UnityProject the default; a game's own in u2ue/adapters/<game>.py
AssetFamily u2ue/assetfamily.py:AssetFamily effects, scene and ui: the facade command for each of the five steps, or ABSENT with why (the generated table above)
Route u2ue/routes.py:Route one switch, the files that read it, its evidence rows, and its state read off those files
Rule u2ue/facts.py:Rule one conformance bake (shared/conformance/*.json) and the Unity version it was measured on
ProbeCase u2ue/probecase.py:ProbeCase one case of the generic particle probe, as data: a real prefab placed by the game's spawn, or a SYNTHETIC system set by name. A run writes its cases file and its Unity window spec, and conform cases goes through it
Window u2ue/verbs/window.py:Window one runner; a window is a JSON spec (Chapter 8)
Capture u2ue/capture.py:Capture one photo run, judged by what it holds, never by its exit code: a system with an error, no background or no frame is NOT CAPTURED, and a frame asked for but not written by THIS run is SHORT. u2ue photo and a trial's photos step judge through it
Readback u2ue/readback.py:Readback one read of built systems and its capture summary. u2ue read and a trial's read step judge through it; systems() streams one system at a time, so a read larger than memory is judged with the same rows
Judge u2ue/judge.py:Judge each judge tool, the trials that run it and its plant, read off the trial specs (no list kept by hand); each is proven by its own --selftest or declared by a trial (u2ue judge --prove)
Trial u2ue/verbs/trial.py:Trial one runner; a trial is a JSON spec
Run u2ue/run.py:Run a run on a snapshot of the toolkit's code (pin()): u2ue trial run pins first, so an edit to the live converter mid-queue cannot change what runs; the owner can stop it gracefully
Pillar u2ue/pillars.py:Pillar the product's pillars, checked by u2ue cycle
Check u2ue/pillars.py:Check one recurring check of a pillar: held, trending, or absent; commit marks one fast enough to run on every commit
CommitGate u2ue/verbs/cycle.py:CommitGate u2ue cycle --commit, the toolkit repo's pre-commit hook: when a commit stages a toolkit file, the commit-marked checks run, trends held to the full cycle's baseline; a red one refuses the commit by name, and U2UE_GATES_OVERRIDE lets a red that is not yours through, logged (commit-gate.jsonl)
LogicPort u2ue/logic.py:LogicPort each step of the logic skill judged by its DONE WHEN (the observable that ends the step) from the records (u2ue logic); the method is the skill
Seam u2ue/seam.py:Seam every interface your model declares, sorted by who implements it: SEAM (an engine fills it), FACET (the model fills it), NONE (no implementer found by text: UNKNOWN, never absent). It gives the list of sockets a host still lacks
Gate u2ue/gates.py:Gate the field gates and the model gates that check runs; logic_diff.py (what parity runs) is still its own tool
HostProject u2ue/hostproject.py:HostProject u2ue host: the game's own .uproject made from the host template, each step judged by its proof line (Chapter 3); it enables the engine plugins the toolkit's Unreal steps run on (Python scripting, editor scripting, and the Cascade-to-Niagara converter whose library the converter writes through), which the effects verbs require of any project
Release u2ue/release.py:Release u2ue release: the package assembled as a repository by one manifest, every exclusion named with its reason; a secret refuses the whole release
ToolkitHistory u2ue/release.py:ToolkitHistory what the toolkit keeps in its own repository and never ships, each with its reason: the instruments it measures itself with and the documents it was built from; a shipped file that still reads one refuses the release
ShippedClosure u2ue/release.py:ShippedClosure what a release ships of each toolkit part: what the facade reaches - by import, by a file its code names, by a build item - and the measured rules; every other file of a part is the reference port's own and is left out with that reason
ReleaseProof u2ue/release.py:ReleaseProof u2ue release --prove PROJECT: a release assembled fresh, made a git checkout of itself (a gate may read git show HEAD: of its own folder), and a second game's check --only selftests run inside it, the way a customer holds it
SelftestRegistry u2ue/selftests.py:SelftestRegistry every tool's own selftest as a row, which u2ue check runs (--only selftests); a project file adds the rows written against its own game; in a release, a row whose tool was kept out is NOT RUN with the release's own reason
RequirementCheck u2ue/requirements.py:RequirementCheck u2ue req: every // REQ: citation in the game's code resolved in the requirement documents the project file names - HOLDS, TAGGED (declared: no designer requirement behind it) or UNRESOLVED, which goes to the designer (Chapter 14)
RequirementSource u2ue/requirements.py:RequirementSource one requirement document or folder of them: cited by line or id (lines), by the sections it defines (sections), or by an entry's name (entries)
MutationRun u2ue/mutation.py:MutationRun u2ue mutate: would any test notice a changed rule - each row of a mutation file applied to a fresh copy of what the project file declares, the tests run there, the file put back; the project's own files are never written (Chapter 14)
Mutation u2ue/mutation.py:Mutation one deliberate change to a rule: its file, the exact text it replaces, the new text, and the claim the tests must protect
PortPlan u2ue/port.py:PortPlan u2ue port: the whole port as ordered stages, in the order of the use case model's epic
Stage u2ue/port.py:Stage one step of the port, of one kind - AUTOMATIC, EDITOR, AI or OWNER - its state read from the records its own verb writes (DONE, TODO, RED, STOP, WAITS, ABSENT, UNCHECKED)
PortRun u2ue/port.py:PortRun the plan run in order: a read by default, --run runs every AUTOMATIC stage that is TODO, a RED stage holds back only its dependents, and running it again resumes
Census u2ue/estimate.py:Census u2ue estimate: what a Unity project holds, read off its files - code lines pure and coupled per folder, the build's scenes, particle prefabs, UI assets
TokenUse u2ue/estimate.py:TokenUse one model call's tokens in the five kinds a price list prices (uncached input, 5 m and 1 h cache writes, cache reads, output), a streamed call counted once
MeasuredRate u2ue/estimate.py:MeasuredRate tokens per unit read from a real port's records, with n, a bootstrap band and a leave-one-out error - or ABSENT with its reason
PriceTable u2ue/estimate.py:PriceTable per-model prices per token kind, read from Anthropic's pricing page and kept with its URL and date (u2ue/basis/prices.json)
Estimate u2ue/estimate.py:Estimate a Census times the rates: tokens per stage, the cache split, the list cost, the confidence, and the saving where one was measured (the cost page)
SliceGate u2ue/slice.py:SliceGate u2ue slice: every check one slice of a logic refactor (such as the MVC move) must pass before it lands - every host builds, the model's tests fail nothing beyond a baseline recorded before the slice, the model gates, Unity's scripts compiled headlessly (from an overlay while the change is in a scratch copy), and parity; it says on every run that it does not prove the game PLAYS the same
EditorLink u2ue/editorlink.py:EditorLink how the toolkit talks to a Unity editor - its state, a recompile, Play and stop, a menu item, and the console's NEW errors since a mark - through the link the project chooses (unity.link: the game's own HTTP bridge, or the package's file channel); a console row the project declares standing (slice.console_standing) is set apart and never counted as new, and a slow domain reload is said with its cost, read from the editor's own log (slice.editor_autoruns.log). play() and stop() answer (ok, detail) only once a status says so (play_state); a status from a stalled main thread (main_thread_stalled - a bridge that answers from its own thread still says "not playing" while the editor is frozen) is no answer, and is asked again before anything is decided on it (settled_status)
ReaderReads vfxport/yaml_field_gate.py:ReaderReads every field the effect reader reads off a particle system, keyed by its module path (ColorModule.gradient), read off the reader's own source: the field gate credits a Unity field only on the module it is read from
StorePackage u2ue/release.py:StorePackage u2ue release --store: the Unity half of the toolkit as an Asset Store UPM product, assembled by its own manifest and held to the store's rules, each a count that must read 0; no package.json without the publisher namespace the UPM enrolment gives. Its assemblies are one main assembly that references no other, and optional ones that extend it where a package they need is installed
PackageCompile u2ue/release.py:PackageCompile u2ue release --store --compile: the store package's C# compiled alone, against Unity's own assemblies and nothing of the project's; package.json's unity field is the editor it compiled against, never a typed version
StoreLayout u2ue/release.py:StoreLayout where the store package's files go: a Package Manager (UPM) package, or a classic Asset Store package - one folder under the project's Assets, every folder with its .meta - built from the same files and held to the same rules
StoreSample u2ue/release.py:StoreSample a sample the store package ships under Samples~ (a tool that works on a game's assets ships assets of its own to try it on): its files read by their own bytes, an asset and its .meta refused unless they pair, and its package.json entry
MvcCensus u2ue/verbs/inventory.py:MvcCensus u2ue inventory --mvc: every MonoBehaviour's state, member by member - runtime state, authored data, references, statics - with where each is written, so a type is sorted into model, view or both from its code, never from its name
SliceLanding u2ue/slice.py:SliceLanding u2ue slice cut / land: a slice prepared in a scratch overlay is written into the owner's live Unity project only after the slice gate passed and the owner has been away long enough; it is compiled, its console judged, and the game PLAYED with a seeded battle before and after, the two compared under compare/ (--battle clicks plays the player's turns through the click path); the live files are restored on any failure or the owner's return. An event kind a slice changes by decision is left out only with --ignore-kinds K --because <why>, or by row (--ignore-rows "6:side!=0"); cut --on stacks a slice on ones not landed yet and slice rebase brings it up to date; an editor left in Play is stopped only where the project says so (slice.idle_play), and the tests only a landing can prove are the project's slice.landing_proves With the owner at the machine he can hand it over, --handed-over "<the owner's words>": no quiet wait, his input not taken for a return, his words in the landing record
SliceStep u2ue/slice.py:SliceStep an editor step a slice declares in its overlay (.slice-steps.json): a menu item the landing runs once the slice has compiled, before the landing proofs and the battle on the new code read what it writes, and the files it writes - backed up with the slice, never taken for another writer's, put back with the slice unless it PASSES; one that does not answer, writes nothing or logs new errors FAILS the landing. For a slice whose data only its own code can write (a new data format and its exporter)
Citation u2ue/citation.py:Citation u2ue cite: a File.cs:N breadcrumb in the model's comments, held to the code it names - a quoted one HOLDS, MOVED (to the line it is on now) or BROKEN; one that gives a file and a quote with no line holds wherever in that file the quote is
ByNameReach u2ue/slice.py:ByNameReach the gate's names check on an overlay: every member a slice turns from a field into a property, or renames, is looked for where code reaches it BY NAME (reflection, an animation binding, a serialized string), and each reach is a finding unless its line says slice: by-name ok
StandingCompileErrors u2ue/slice.py:StandingCompileErrors the unity check's judge: when the overlay's compile against the model's source has errors, the live project is compiled the same way without the overlay - an error both report word for word, in a file the overlay does not carry, is STANDING (another writer's, named in the verdict); every other error is the slice's and fails it, so does a standing one in a file the overlay carries, and so does a slice whose scripts sit in an assembly a standing error kept from compiling (NOT COMPILED)
TextAnchorReach u2ue/slice.py:TextAnchorReach the names check's second half: a test that reads a script's text by path (File.ReadAllText("Assets/...cs"), or a helper handed the path, Repo("<project>/Assets/..."), or only the script's name, Scripts("<Name>.cs") or Path.Combine(root, "<Model>", "<Name>.cs"), which resolves in the Unity project and in the model's own folders, its scan; a folder listing's "*.cs" names no script) and looks for a literal breaks where no compiler looks once the slice moves that literal - each such literal is a finding, with the same slice: by-name ok for a deliberate one
LandingProof u2ue/slice.py:LandingProof the tests a project declares only a landing can prove (slice.landing_proves): they read what the owner's editor recorded, so the landing has the editor record them again and runs them against the engine's own model (model_from), its replays compared
SliceBlobs u2ue/slice.py:SliceBlobs the file versions a stacked slice was cut on or rebased onto, kept by their content (.slice-blobs/), so slice rebase merges three ways
LineEndingKeep u2ue/slice.py:LineEndingKeep the gate's eol check: every overlay text file keeps its live file's line endings
SharedScripts u2ue/slice.py:SharedScripts the gate's build and tests on an overlay: a Unity script that a headless .NET project also compiles is built and tested again with the overlay's copy swapped in, never only as it is live
EditorAutoRuns u2ue/slice.py:EditorAutoRuns the suites the owner's editor runs on its own after a compile (slice.editor_autoruns): a landing runs each through its menu item and waits for its summary in the editor's log before it plays
PresentationTrace u2ue/slice.py:PresentationTrace what a seeded battle SHOWED, in order, read from the editor's log (slice.presentation): the camera's requests, the technique stages and the cutscene shots, compared like the battle's events - each line exact, masked or leave_out as the project declares, with drop for text the editor writes into a line from outside the battle (its window's focus)

The table answers "where is X" without reading code; u2ue find answers it for everything else, and uml where <Name> for a class of the game's model. How a new concept becomes a class is toolkit work: Chapter 18.

3. Installation and the project file

Who this is for: the developer porting their own game - what to install, how to describe the game in one project file, how to make its Unreal host, and how to prove the install works. After it, every later chapter's commands run on your machine against your game.

Requirements

component version used what needs it
Windows 11 the Unreal runs are driven from native PowerShell
Python 3.13 every tool; the facade
PyYAML 6.0 with libyaml reading Unity YAML (libyaml is about 7x faster; measured equal output)
markdown (Python) 3.8 building this manual's HTML edition only
.NET SDK 8.0 or later (10.0 used) the runtime library and its tests; an UnrealSharp host (below)
Unreal Engine 5.7 build, read, photo: Niagara, the CascadeToNiagaraConverter plugin (its FXConverterUtilitiesLibrary writes the Niagara stacks), the engine's Python scripting (UnrealEditor-Cmd -ExecutePythonScript)
UnrealSharp, the plugin that runs C# inside Unreal the host project's C# hosts for the game's model (Chapter 5)
Unity Editor the game's own only for measurement windows and reference photos, in the game's own editor; the toolkit never launches one

The Unity project must be serialized as text (Edit > Project Settings > Editor > Asset Serialization: Force Text): YAML .prefab, .unity, .mat, .asset and .meta.

Where the toolkit lives

Beside the facade (u2ue), the toolkit is a set of folders called parts: the converter (vfxport), the effect tools, the scene tools, the lane part (the queues and the report builder), the measured Unity rules and the UI converter. They are named once, in u2ue/tools.py (PARTS); set the environment variable U2UE_TOOLKIT_ROOT to move them as a whole. Run every command from the toolkit's root:

py -m u2ue                       # every verb
py -m u2ue find <words>          # search the toolkit

The project file

One file per game, u2ue/projects/<game>.json (or anywhere: --project takes a path). A complete one, for a game whose effects are simply its particle prefabs - it ships as u2ue/projects/example.json, to copy and fill in:

{
  "name": "mygame",
  "adapter": "unity_project",
  "about": "the project file a customer copies and fills in (manual, Chapter 3): every <...> is a path on their machine. Copy it to u2ue/projects/<game>.json - or keep it anywhere and pass its path: py -m u2ue --project <path> info",
  "unity": {
    "root": "<unity project>",
    "assets": "<unity project>/Assets",
    "version": "2021.3.21f1",
    "editor": "<Unity 2021.3.21f1 install>"
  },
  "effects": {
    "key_source": {"kind": "particle_prefabs", "roots": ["Assets"]}
  },
  "unreal": {
    "uproject": "<unreal project>.uproject",
    "engine": "<Unreal Engine 5.7 install>",
    "content_root": "/Game/U2UE/MyGame"
  },
  "work": {
    "effects": "<work>",
    "ir": "<work>/ir",
    "guid_index": "<work>/guid_index.json",
    "resolve": "<work>/resolve.json",
    "records": "<work>/records",
    "photos": "<work>/photos",
    "inventory": "<work>/inventory"
  },
  "code": {
    "roots": ["Assets/Game", "Assets/GameShared"]
  },
  "requirements": {
    "root": "<unity project>",
    "sources": [{"name": "Requirements.txt", "path": "Docs/Requirements.txt", "kind": "lines"}],
    "tags": {"plumbing": "engineer-owned: no designer requirement behind it"},
    "roots": ["Assets/Game", "Assets/GameShared"]
  },
  "mutation": {
    "root": "<model root>",
    "copy": ["<Model>.Core", "<Model>.Core.Tests"],
    "test": "<Model>.Core.Tests/<Model>.Core.Tests.csproj"
  }
}
field meaning
name the project's name
adapter unity_project (Unity's own rules) or a game adapter's name (u2ue/adapters/<name>.py, Chapter 18)
unity.root, unity.assets, unity.version the Unity project, its Assets folder, its version (measured rules are checked against it)
unity.editor (optional) that version's Editor install: its built-in shaders and materials are named off unity_builtin_extra (the Editor's file of built-in resources)
effects.key_source what the effects are: {"kind": "particle_prefabs", "roots": [...]}, or a game resolver through its adapter
unreal.uproject, unreal.engine, unreal.content_root the Unreal host, the engine, the content folder the systems are built under
work.* where the work goes: the IR, the guid index (every Unity asset GUID to its path, read off the .meta files), the key list, the records, the photos, the code inventory
code.roots the game's OWN C# folders (u2ue inventory --survey lists every folder first; vendor packages live in Assets too)
model.root, model.layers, model.scan, model.hosting, model.unreal_links, model.hosts the engine-free model, once the game has one (scaffold, the verb that creates the model's projects, writes the first four), and where each engine's host code is (Chapter 5)
parity.dir, parity.engines where the model's per-runtime digests (one runtime's answers to the rule cases, floats as bit patterns) are written, and the runtimes parity requires (Chapter 5)
mono.faithful (optional) the Editor-recorded digest digest faithful re-measures Unity's standalone Mono against (Chapter 5)
unreal.host (optional) the game's own Unreal project for u2ue host (below, and Chapter 13)
requirements (optional) the game's requirement documents (sources: a name, a path, a kind - lines, sections or entries), the tags that declare no requirement exists and why, and the code roots whose // REQ: citations u2ue req checks against them (Chapter 14); relative paths are read from its root
mutation (optional) what u2ue mutate copies to try a mutation on (copy: folders, or globs such as Shared/*.cs, from its root) and the test project it runs there (test) - the copy must hold everything that project builds from (Chapter 14)

u2ue/projects/ ships example.json alone: the reference port's own project files (a game adapter, a model, parity) and the second game's stay in the toolkit's repository - each names its machine's paths.

Check it:

py -m u2ue --project <game> info       # every path OPENED; exit 1 when an input is missing

The Unreal host

The verbs that run Unreal (build, read, photo, host) need a host project with the plugins above, and run one headless Unreal at a time from native PowerShell (Git Bash hands PowerShell a PATH without the dotnet entry UnrealSharp looks for, and the verbs refuse such a PATH). A game builds under its own content_root (/Game/U2UE/<Game>).

u2ue host makes your game its OWN Unreal project: name it in the project file's unreal.host block, then run the steps one at a time. Each step is judged by the line in its own log that proves it, never by an exit code. Chapter 13 has the block's fields and each step in full; on a machine with no Windows SDK installed, the C++ compile needs an AutoSDK root (a folder that holds a Windows SDK and a toolchain), which the block's sdks_root hands to the build as UE_SDKS_ROOT. The managed project the steps make is the host's C# project, which UnrealSharp compiles and the engine loads.

py -m u2ue --project <game> host plan        # every step: its command and the line that proves it
py -m u2ue --project <game> host create      # the .uproject from the toolkit's host template, renamed
py -m u2ue --project <game> host install     # each plugin cloned at its pinned commit; the toolkit's own copied
py -m u2ue --project <game> host compile     # the editor target (UnrealSharp generates its C# glue, the bindings to the engine's types)
py -m u2ue --project <game> host generate    # UnrealSharp's own command makes the managed project - no editor dialog
py -m u2ue --project <game> host wire        # the model, the digest cases and the host templates into it
py -m u2ue --project <game> host publish     # to both folders the engine may load from
py -m u2ue --project <game> host run         # headless: the host answers the digest; then `parity --require Unreal`
py -m u2ue --project <game> host status      # each step: proven, failed, or not run

Measured on the second game: from nothing to parity --require Unreal exit 0 in 9 minutes, the C++ compile 255 s of it.

Verifying the installation

Scope: the toolkit itself, on this machine. Precondition: the requirements above are installed and a project file exists. Minimal guarantee: a tool whose selftest fails is named. Success guarantee: every selftest passes, the runtime library's tests pass, and the manual matches the code. Trigger: the toolkit is installed or updated.

py -m u2ue --project <game> check --only selftests     # every tool's own selftest
dotnet test u2ue/runtime/U2ue.Runtime.Tests              # the runtime library
py u2ue/manual/build.py --check                          # this manual is current

The Unreal-run tools

The install is done. The last two sections are for when your builds grow long: how the verbs launch Unreal, and how a long build and a trial share the one Unreal.

Every verb that runs Unreal launches it through ue_headless.ps1, which refuses a launch that could open a window, passes -DeterministicAudio (audio goes to Unreal's non-realtime renderer, never to the machine's sound device), and kills a runaway run at a time or log-size cap; the verbs refuse while another Unreal runs, so there is one at a time. build builds its keys in one headless run, in compile batches (--batch), and resaves only the systems it made; split a whole game into chunks by handing each chunk's key list to --keys. A texture, material parent or instance built before is reused only when nothing it came from changed. Chapter 13 has each tool the build, read and photo verbs run.

Unattended queues and the pause protocol

A whole-game build runs for hours, unattended, and there is one Unreal slot. Two rules keep a long build and a trial from spoiling each other:

  • A trial never shares the Unreal slot with a running build. The verbs that run Unreal refuse while the host is busy, and never interleave. If you script a long series of builds yourself, give it a pause point between chunks: the series waits while a pause file exists, the trial runs its whole chain (build, resave, read, every check and its plant, photos), and only then is the pause removed. Nothing removes a pause but the one who set it. No verb provides this pause; it belongs in your own queue script.
  • A trial is data, not a copied script. py -m u2ue --project <game> trial run <spec.json> runs one from a spec: build, resave, read, judge (with its plant), photos. It runs alone, waits until no other Unreal runs before each Unreal step, and runs from a snapshot of the toolkit's code, so an edit to the live converter cannot change a trial half way. trial stop ends it at the next step boundary, never mid-step. A project supplies only its key lists and its work folders.

4. Tutorial: a first port, step by step

Who this is for: the developer porting their own game - the commands of a whole port in order, with real output from a game the toolkit was not built on. After it you can take your own game from its project file to its first report, and you know the command and the chapter for each stage after that.

This chapter takes a game the toolkit was not built on - a different studio's project on Unity 2021.3 - through a port. Steps 1 to 8 show what each printed on 2026-10-15; steps 9 to 18 are the rest of the port, each with its command and what it proves. The game's name is written <game> and its folder names are shortened; the numbers are as printed.

Scope: one game, from its project file to its first report. Precondition: the toolkit is installed and verified (Chapter 3). Minimal guarantee: every path the project names is opened, and every key the game must account for is listed before anything is built. Success guarantee: the acceptance page and the numbers, each number read from a record or naming the record it waits for. Trigger: a game the toolkit was not built on is to be ported.

The one command

Three lines carry the whole port: one prices it, two run it. The numbered steps after this section are what they run, one at a time.

py -m u2ue estimate --unity <unity project> --roots <the game's code folders>    what the port will cost, before you start
py -m u2ue --project <game> port                                                 every stage, read from its records; the next action
py -m u2ue --project <game> port --run                                           run every stage a verb can; stop where one cannot

estimate needs no project file (What a port costs has what it prints and how sure it is). port reads each stage's state from the records its own verb writes, so running it again resumes where the port stands. On this game, on 2026-10-17, with the paths and three long lines shortened:

py -m u2ue --project <game> port
u2ue port: <game> - reading every stage (nothing runs)
  [OWNER    ] project    DONE      describe the project (paths, code roots) - info exit 0
  [AUTOMATIC] inventory  DONE      read the game's C#, type by type - <work>/inventory/inventory.json
  [AUTOMATIC] classmodel DONE      the game's class model off its own code - <work>/inventory/uml
  [AI       ] logic      DONE      move the rules into an engine-free model - every step of u2ue-logic DONE, JUDGED or NOT RUN (9 DONE of 12)
  [AUTOMATIC] host       DONE      the game's own Unreal project, the model running in it - host status: every step PROVEN
  [AUTOMATIC] scene      ABSENT    the scenes as Unreal levels, held to Unity - the project file names no scene block
  [AUTOMATIC] extract    DONE      the effects read into the engine-neutral IR - <work>/u1e-ir.json
  [AUTOMATIC] gates      DONE      every Unity field the IR carries read or excused - check --only gates exit 0
  [AUTOMATIC] build      TODO      the Niagara systems built - no build record <work>/records/u1e-build-u2ue.json
  [AUTOMATIC] read       WAITS     the built systems read back frame by frame - waits on build
  [AUTOMATIC] photo      WAITS     the built systems photographed beside Unity's frames - waits on read
  [EDITOR   ] ui         UNCHECKED the UI screens captured, converted, rebuilt - the UI verb has no read-only status
  [AUTOMATIC] parity     DONE      the rules agree on every runtime, by the bit - parity exit 0
  [AUTOMATIC] report     DONE      the acceptance page from the records - <work>/report/<game>_acceptance.html
  [OWNER    ] owner      STOP      the owner's decisions the page asks - read the acceptance page and answer them
NEXT: build - `py -m u2ue --project <game> build`, or `port --run --with-unreal` (it launches a headless Unreal: one at a time)

Each stage is one of four kinds. AUTOMATIC: a verb does it, and --run runs it. EDITOR: it needs a free Unity editor, so port names the window and never opens one. AI: the logic, done by the u2ue-logic skill in Claude Code, with u2ue-long-run keeping the session going (Chapter 15). OWNER: a decision only the game's owner can make. A stage that launches a headless Unreal runs only with --with-unreal, one Unreal at a time.

Each stage's state is read, never assumed: DONE; TODO (an AUTOMATIC stage not done yet, which --run runs); WAITS (a stage it depends on is neither DONE nor ABSENT); STOP (it needs a person, the AI or an editor, and names the one question); RED (its check ran and failed); ABSENT (the project file names nothing for it); UNCHECKED (no read-only check exists for it yet). A RED stage never runs, and it holds back only the stages that wait on it. ABSENT and UNCHECKED stages are said, never skipped silently.

1. Describe the game and open every path

Write u2ue/projects/<game>.json (Chapter 3 has a complete one), then:

py -m u2ue --project <game> info
project <game> (u2ue/projects/<game>.json)
  unity.root           dir       <unity project>                     ok
  work.effects         out-dir   <work>                              ok (exists)
  work.photos          out-dir   <work>/photos                       to be created (its parent exists)
  unreal.uproject      file      <unreal project>.uproject           ok
  unreal.content_root  game-path /Game/U2UE/<Game>                    ok (an Unreal content path)
  adapter: unity_project (spawn rules unity)
  key source: {'kind': 'particle_prefabs', 'roots': ['Assets']}

Every path the file names is opened; an input that is missing exits 1.

2. Find the game's own code

Vendor packages live in Assets beside the game's code, so the toolkit never guesses which folders are the game's:

py -m u2ue --project <game> inventory --survey
  AssetStore     4226   + 917 in Editor folders
  GameCode       1907   + 55 in Editor folders
  GameShared       25
  ...

Name the game's folders as code.roots in the project file.

3. Inventory the code

py -m u2ue --project <game> inventory
u2ue inventory <game>: 1987 files, 2453 types (plain 1384, MonoBehaviour 789, ScriptableObject 160, base outside the scanned code 88,
EditorWindow 15, Editor 12, PropertyDrawer 5); 1148 pure rules; -> <work>/inventory
  serialized data                  473 types   1708 sites
  platform (log, files, prefs)     365 types   1525 sites
  spawn / destroy                  311 types   1049 sites
  lookups                          275 types    661 sites
  coroutines / Invoke              273 types    997 sites
  transform                        222 types   1652 sites
  UI                               134 types    373 sites
  time                             112 types    254 sites
  physics                           83 types    317 sites
  input                             75 types    236 sites
  animation / timeline              54 types    309 sites
  ...

<work>/inventory/inventory.md lists every type's Unity calls by family (each family names its section of u2ue/BASICS.md, whose topics are Chapter 5's "Topic by topic"), the 1148 types that use no Unity API (what moves into an engine-free model first), and every MonoBehaviour's script execution order with its lifecycle methods - the table Unity's frame order is rebuilt from in the model. Chapter 5 is what to do with it. Read the counts as a plan: this game has physics in 83 types and animation in 54, which the toolkit does not cover (Appendix B), and you know that on day one.

4. Read the data the inspector holds

py -m u2ue --project <game> data --from Assets/<data folder>/<data asset>.asset --script <DataClass> --tsv data.tsv
u2ue data <game>: 1 component(s) in Assets/<data folder>/<data asset>.asset
  None  fileID 11400000  23 fields

Every serialized value as the file stores it: 487 leaf values in the TSV for this game's ScriptableObject, with the avatar-mask reference resolved to its asset path. The values are read, never retyped into the port. (The game's own asset and class names are written <data asset> and <DataClass>.)

5. Extract the effects

py -m u2ue --project <game> extract
    - Snow_Particles   active=True  depth 0 loop=True  dur 5  life (2.2, 2.2) size (0.15, 0.3) space World ...
        render Stretch  shape Box(enabled True)  rate 500.0 bursts []  modules ['colorOverLifetime', 'rotationOverLifetime', ...]
    material .../Snow_Particles.mat
        shader Legacy Shaders/Particles/Alpha Blended (None)  blend {'_SrcBlend': 1, '_DstBlend': 0, '_ZWrite': 1}
REFUSED BY KEY: 4 of 60 READ key(s), each named above
u2ue extract: 60 READ key(s): 56 IR file(s) with 189 emitter(s), 4 refused by name, 0 dropped, 0 foreign path(s)
  REFUSED unity.prefab.5ccd...: .../Winter Door.prefab: PrefabInstance 4843689442982340616: modification target 1211823196678298638 ...

This writes the guid index (to work.guid_index), the effect keys (every prefab holding a ParticleSystem, by the default adapter, to work.resolve) and one IR file per key (under work.ir), and prints a one-line summary of what was read for every emitter. Four keys are refused, each with the object the reader could not follow; nothing is dropped silently. What the effects path does not cover (VFX Graph assets, particle systems authored in scenes) is listed with counts.

6. Check before building

py -m u2ue --project <game> check
...
u2ue check: the measured rules' Unity versions against project <game>
  163 measured Unity bakes; this project is Unity 2021.3.21f1
       163 measured on Unity 6000.3.16f1    UNVERIFIED for Unity 2021.3 - re-measure where it matters
  163 of 163 rules this project's build uses were measured on another Unity: its report must not call them measured for it
u2ue check: PASS

check runs every tool's own selftest, the field gates over this project's IR (an unread Unity field fails here, not as a silent gap later), the measured rules' Unity versions against the project's, and the model gates (no model yet: said so). Here every rule is reported unverified for this Unity: the build still runs, and the report says so.

7. Build, read, photograph (the Unreal host)

py -m u2ue --project <game> build --dry     # the plan and the host's state - always first
py -m u2ue --project <game> build
py -m u2ue --project <game> read --tag <TAG>
py -m u2ue --project <game> photo --tag <TAG>

Run from native PowerShell, one headless Unreal at a time. A build keeps its record as records/u1e-build-<TAG>.json (the tag is u2ue unless build --tag names another), and read and photo take the same tag to find the systems that build made. Appendix A has the reference port's numbers for these steps.

8. Report and measure

py -m u2ue --project <game> report --out <game>.html
py -m u2ue --project <game> metrics
u2ue metrics - <game> (every number from a record; definitions: u2ue/verbs/metrics.py)
  keys      60: NEVER BUILT 56, IR REFUSED 4; 0 drawn, 0 of them with a named gap; 0 from the acceptance rebuild
            the rules behind 'measured' were measured on Unity 6000.3.16f1; this project is Unity 2021.3.21f1 - UNVERIFIED for it
  machine   ABSENT: no per-key seconds in the chosen build records
  data      ABSENT: no <work>/records/checks_summary.json - the readback sweep has not run
  image     ABSENT: no sheets listing <work>/records/fx18_sheets.txt - the photo pass has not run

Before any build the page already lists every key the project must account for, and every number it cannot compute yet says which record it is waiting for. Chapter 10 defines every number.

Part two: the rest of the game

Steps 1 to 8 brought the effects to a first report. A port also moves the game's code, its scenes, its UI and its Unreal project. The steps below are the same port continued, in the order that keeps each step's input ready for the next. Each step names its command and what that command proves; the chapter named beside it has the full procedure, the options and the traps.

9. Draw the class model of one slice

py -m u2ue --project <game> uml extract
py -m u2ue --project <game> uml mermaid --focus <TypeA> <TypeB>

A slice is a handful of types that hold one rule of the game; the code moves one slice at a time. extract reads the class model off the game's own code roots (and its engine-free model, once there is one). mermaid --focus draws one slice with every member a real one. The diagram comes before any code moves, and a diagram that names a member the code lacks is refused. Chapter 5, and the u2ue-logic skill's step 2.

10. Make the engine-free model

py -m u2ue --project <game> scaffold --name <Model> --dir <DIR> --dry
py -m u2ue --project <game> scaffold --name <Model> --dir <DIR>

The first line shows what would be written, and the second writes it. You get a Core project (<Model>.Core, the model's own C# project) that references only the toolkit's runtime library, a headless test project, and the project file's model block. Then the verb builds both and runs the model gates. Exit 0 means the model exists, compiles, and no engine reaches it. A second scaffold is refused, so this never overwrites. Chapter 5, step 6.

11. Move the slice and prove it on Unity's own runtime

Move the slice's rules into the Core, each with its test, then:

py -m u2ue --project <game> digest run --entry <Ns.Class.Method> --cases <Cases.cs>
py -m u2ue --project <game> digest faithful
py -m u2ue --project <game> parity

digest run answers the rule's cases with no engine at all, on CoreCLR (.NET's own runtime, the one the Unreal host and the headless runs use) and on the project's Unity version's own Mono runtime, writing each runtime's answers as a digest. digest faithful proves that the no-editor Mono run gives the same rows as the Editor does. parity compares every runtime the rules run on by float bits, and names each row that differs. Chapter 5, step 7, and Chapter 14.

12. See where the logic port stands

py -m u2ue --project <game> logic

Each step of the u2ue-logic skill is judged by its own DONE WHEN, read from the project's records, and the verb names the step to take next. An AI model doing the port starts every session here instead of working out the state again. Chapter 5.

13. Find what Unreal cannot place as Unity does

py -m u2ue --project <game> shear --from Assets/<scene>.unity

This lists every node whose transform chain Unity can draw and Unreal's transform cannot hold (a non-uniform scale under a rotation shears), with the error in centimetres and whether the node draws. Whether to accept, bake or fix each error is your call, made with its number. Chapter 6.

14. Bring a scene across

py -m u2ue --project <game> scene --dry
py -m u2ue --project <game> scene export
py -m u2ue --project <game> scene import
py -m u2ue --project <game> scene readback
py -m u2ue --project <game> scene check

--dry opens the scene's paths and shows the Unreal host's state. export runs in the game's own Unity Editor, in a window: the verb itself never touches an editor, and prints the trigger the window drops (.RUN_SCENE_EXPORT, the file that starts the export). import brings the glTF into a new Unreal level through the engine's own scene pipeline, and readback reads the saved level back headless. check is the fidelity gate: hierarchy, materials, textures, lighting and placement, held to Unity's files and to the scene's own measured baseline. Chapter 6.

15. Convert the UI

py -m u2ue --project <game> ui convert <capture dir> --screen <NAME>
py -m u2ue --project <game> ui test

convert turns one captured screen into a folder Unreal reads: the capture, its sprites, and each TextMeshPro font's TTF, proven by identical glyph indices. test runs the generic uGUI and TextMeshPro library's own tests headless. The capture itself runs in the game's Unity Editor in Play mode. The package does not ship that capture as an Editor assembly yet (Appendix B), so ui capture refuses and says why. Chapter 6.

16. Make the game's own Unreal project

py -m u2ue --project <game> host plan
py -m u2ue --project <game> host create
py -m u2ue --project <game> host status

plan lists every step (create, install, compile, generate, wire, publish, run) with the command it runs and the log line that proves it. Run the steps one at a time, from native PowerShell, and status shows each one as proven, failed, or not run. The run step is proven only when the model's digest file is written after the run started. Chapter 13.

17. Hold the effects to Unity on numbers

py -m u2ue --project <game> conform cases --name <run>
py -m u2ue --project <game> conform diff --unity <particle-cases record> --unreal <readback record> --report <FILE>
py -m u2ue --project <game> conform latest --run <run>

cases writes one probe case per effect key, plus the Unity window and the Unreal read that measure them. After both have run, diff judges every emitter of every key on its live count and its first birth, paired by file id. latest prints the share that holds, from the newest stamped report. Chapter 9.

18. Check every pillar

py -m u2ue --project <game> cycle --dry
py -m u2ue --project <game> cycle

Every promise of the toolkit is checked: PASS, FAIL, HELD by a named decision, or ABSENT where no check exists yet. Red stops the cycle. Run it before any report. Chapter 14.

Where to go next

  • The game's code, in full: Chapter 5, with each part of a Unity game in its "Topic by topic".
  • A behaviour that must match exactly: Chapter 8, and the tools that run it: Chapter 12.
  • An effect family the converter refuses: Chapter 7's route protocol, then Chapter 11.
  • Something went wrong: Chapter 16.

5. Porting the game code

Who this is for: the developer porting their own game - how its code moves into one engine-free model that both engines run, what the toolkit gives at each step, and how to prove the answers agree. After the method and the playbook you can move one slice of your game's rules and prove it on every runtime; the later sections are reference to come back to.

The particle effects are content; the game itself is code: MonoBehaviours, coroutines, inspector values, the transform chain. The chapter's parts:

  • The method (steps 1 to 8): the order of work, what the toolkit gives at each step, and its real output.
  • Topic by topic: each part of a Unity game - what Unity does, what Unreal offers, the route that worked, what the toolkit gives.
  • What the field says about the model: what published engines and authors say about the model's choices, and what a port should take from it.
  • The logic playbook: the method as the u2ue-logic skill (u2ue/skill/u2ue-logic/SKILL.md) an AI agent follows, each step with its command and the observable that ends it.
  • The model in depth, then its recipe, gates and traps: the seams, the event contract and the checks your model needs.
  • The model's tools and the effect ledger: what the package ships around the model.

Scope: the game's code - its rules, its per-frame order, its data. Precondition: a project file names the game and its code folders. Minimal guarantee: what the toolkit cannot do for a rule is said, and the model's gates stop an engine reference. Success guarantee: one engine-free model both engines run, with the same answers by the bit. Trigger: the game's rules live in MonoBehaviours, which Unreal cannot run.

The decision everything follows from

Do not translate MonoBehaviours into Actors one by one. Move the game's rules into an engine-free model - plain C# that references no engine - and write one thin host per engine. Unity and Unreal then run the same model, and the only differences left are the hosts', which is what makes the port provable. It splits into two layers: the rules (state and seed in, state out) and the presentation (the per-frame look: camera, popups, motion). The toolkit's Unreal hosts are UnrealSharp C#, with C++ only where UnrealSharp cannot reach.

flowchart LR
  subgraph model["engine-free model (plain C#)"]
    R["rules: state + seed -> state"] --> PR["presentation: what to show, frame by frame"]
  end
  PR -->|view seams| UH["Unity host: MonoBehaviours"]
  PR -->|view seams| EH["Unreal host: UnrealSharp actors"]
  PR -->|view seams| TH["headless test host"]
  RT["U2ue.Runtime: Unity's frame, clock, coroutines, platform"] --> model

MVC: the shape the logic moves into

A MonoBehaviour does three jobs at once: it holds the game's state, it runs the game's rules, and it draws. Unreal cannot run a MonoBehaviour, so a port has to pull those jobs apart, and they need somewhere to go. u2ue ports a game into Model, View, Controller (MVC), with commands going in and events coming out. The u2ue-mvc skill holds the same rules for an AI model.

  • Model (UnitModel, BattleModel): the state of one thing and the rules about it, in plain C#. Think of a referee with a scoresheet: it decides what happens and writes it down. It never draws, never waits, and never calls the engine.
  • Rules (DamageRules, StatusRules): plain classes grouped by topic whose methods take Models, so "how damage works" is in one file. They take the Model class itself, never an interface written for one rule.
  • Command (UseTechnique, MoveTo, EndTurn): what the player or the AI asks for. Event (Moved, Hit, StatusEnded, Died): what happened, in order. A scene's Model has one entry point, Apply(command), and it returns the events.
  • Controller (BattleController): the stage manager, one per scene, not one per object. It turns input into commands, gives them to the Model, and plays the returned events through the Views one at a time with U2ue.Runtime.PlaybackQueue. Input waits until the playback has caught up.
  • View (UnitView): the actor on stage, a MonoBehaviour in Unity or an actor in Unreal. It holds the id of the Model it shows and plays the events that name it. It decides nothing.
  • View model (HudViewModel): the scoreboard the audience sees, the state as shown. It moves on only as events finish playing, so a health bar drops when the hit lands, not before. There is one per screen (the HUD, a menu).
  • Record (UnitRecord): what lasts between scenes, such as a unit you own with its level and gear. A Model is made from its Record when a battle starts and writes back what the game keeps when it ends.
flowchart LR
    input["click or AI choice"] --> controller["BattleController"]
    controller -- "command" --> model["BattleModel and its UnitModels"]
    model -- "events, in order" --> controller
    controller -- "one event at a time" --> view["UnitView, BattleView"]
    controller -- "as each event finishes" --> hud["HudViewModel"]

One attack, end to end. Unit A uses a technique on unit B, and B's neighbour C can intercept hits. The player clicks B; the Controller makes the command "A uses X on B" and calls Apply. The damage rules check A's action points, roll the hit with the battle's seeded random numbers and look at the board: C is next to B and intercepts, so C takes the hit. That rule needs the board and a second unit, so it belongs to the battle, not to one unit. C loses health, and its Sleep ends because it was hit. Apply returns A used X; C intercepted; C took 12; C's Sleep ended, and the Controller plays the list: A's cast, then C's hit, then the health bar, then the Sleep icon going. Unity, Unreal and the headless runner run every step but the last on the same code, so they cannot disagree.

Why MVC, and not another pattern.

  • MVVM binds a screen to the latest state. A turn-based game has to show the order of what happened, so a world bound to the latest state shows a unit dead before the shot lands. MVVM fits the HUD and menus, and that is where it is used: the view model.
  • ECS (entities and components processed by systems) pays off with thousands of entities. A tactics or card game has tens, and ECS spreads one unit's behaviour across many systems, which is harder to read.
  • Model-View-Update (one pure update function, with the view drawn from the state) is MVC with immutable state. It needs the same event playback for animation, and copying a large model on every change costs more without reading any simpler in C#.
  • MVC with commands and events reads as one sentence: input, controller, model, events, view. Its routing is boilerplate, and an AI writes boilerplate; a person reads the shape.

Sorting every MonoBehaviour

Read what each one holds, not what it is called:

  • It holds game state and runs rules (a unit, a tile, a card, the turn order): a Model and a View. The MonoBehaviour becomes the View, and its state and rules move to the Model.
  • It only presents (a health bar, a VFX player, a camera follow, a menu animation): a View only. It plays events or reads a view model, and it gets no Model.
  • It is plain C# with no Unity call (the inventory's pure types): a Model or Rules, moved as they are.
  • It turns clicks and keys into actions: part of the Controller, or an input source the Controller reads.
  • It is a manager holding a bit of everything (a GameManager singleton): it is split. Its state goes to the scene's Model, its flow to the Controller, and its scene references to the Views.
  • It only holds authored data (a ScriptableObject, a config component): data the Model reads (u2ue data), neither Model nor View.

What a type holds is read, never guessed from its name: py -m u2ue --project <game> inventory --mvc is the census. It lists every MonoBehaviour's state member by member - RUNTIME (private, unserialized data), AUTHORED (Inspector data, with the write sites the game's runtime code makes, so state kept in a public field shows), REFERENCE (an engine object, a package's type, another MonoBehaviour), STATIC and UNPLACED (a type no source names) - and, beside each RUNTIME member, the model's members of the same name: the two-homes candidates. RUNTIME also counts a View's own presentation state (a timer, an animation's progress), so the census is the evidence and the label is a person's reading of it. In the reference port a first pass by type alone named 51 MonoBehaviours as holding game state; read from the census, 8 did.

When the rules are shared but the order is not: one sequence, a host per engine

Moving the rules out of the MonoBehaviours is not the end of it. In the reference port every rule a status landing needed was already in the Core, and the two engines still disagreed, because each one assembled those rules in its own ORDER: Unity's unit method called them in the shipped order with popups and sounds in between, and the headless host had a shorter assembly of its own. Measured on the day the order moved: the headless one skipped nine item and ability riders, never applied an immediate payload on contact, dropped a first landing's bonus stacks, and told the synergy system about each status twice. No rule was wrong. The order was.

So the order moves too, as three small pieces:

  • A sequence in the Core (StatusApplySequence, DamageIntakeSequence, DeathSequence): the steps of one game moment, copied step for step from the engine's shipped method, with that method's line numbers written beside each step. It is generic over the unit type, so both engines run the same code.
  • A unit seam (IStatusApplySequenceUnit<TUnit>): the few writes the sequence makes on a unit's own lists and latches.
  • A host (IStatusApplySequenceHost<TUnit>): the moments the sequence hands back to the engine, named for what happened - "it was immune", "it stacked", "it was added". Unity's host plays the popup and the sound there; the headless host writes a line; the Unreal view draws from the one event the sequence writes into the stream.

The engine's method then becomes a single call, Apply(this, data, applier, host), and the rest of the old body is the host's handful of methods, each holding exactly what the old body played at that point.

flowchart LR
    caller["the technique, a tile, an item"] --> method["Unit.AddStatus: one call"]
    method --> sequence["StatusApplySequence.Apply (Core)"]
    sequence --> rules["rules: admit, immunity, stacks, riders"]
    sequence -- "immune / landed / stacked / added" --> host["the engine's host: popups, sounds, lines"]
    sequence -- "one StatusApplied" --> stream["the event stream: what Unreal draws"]

Move, do not rewrite. A defect found while moving the order is kept, and pinned by a test whose name says "as in Unity", because the two engines must agree before either changes. The reference port kept three that way, among them two items that can never fire because their trigger sits inside a branch their afflictions never reach. Each fix is the owner's decision, made as its own slice with its own test.

Prove the engine that plays it, on the model it loaded. The Unity half of a sequence lands only while the owner is away (u2ue slice land; an editor left in Play refuses it unless the project says an idle Play session is the landing's to stop, slice.idle_play with its reason, and then only after the quiet wait with no agent holding the editor), and a test that compares what the editor recorded with a reference fight is run on the plugins the editor actually loaded. Stacked slices make that matter: each earlier slice ships an older model than the tree's, and judging its recording on the tree's model fails a recording that is right. The same holds for what the editor reads while it records: a reference file the test suite writes from the tree's model is written again from the engine's model just before the editor records (slice.landing_proves.replays) and held read-only until it has. In the reference port a test run rewrote it two seconds before the editor read it, and a slice with nothing wrong failed its landing.

Announce each moment once. When the order moves into the Core, it also becomes the one place that tells the view what happened. In the reference port two layers had each been announcing the same moment: the unit's intake said "this unit took the hit", the technique that caused it said so again, and the view kept a table to swallow the repeat. Moving the announcement into the sequence and deleting the copies is not cosmetic. Measured on 120 seeded battles: the copies had made the view play an element sound for four kinds of rider damage the game plays no sound for, and a burning tile announced the damage it asked for, so the view floated a number over a unit whose shield had taken all of it. Each copy removed was one of those, and nothing else moved.

A tick is its own moment. A status that hurts every turn moves HP through the same intake as any other damage, so the intake would announce the tick's damage while the tick announces itself. The fix is a sequence for the tick too, and a latch that belongs to the battle, not the unit: while a status's own tick runs, the intake inside it says nothing, on whichever unit it lands. Make the latch exist on every engine before any engine's intake starts announcing, or one engine reports every burn twice.

A local the engine kept must stay a local. The engine's tick loop kept a copy of the entry it was ticking in a local variable. The first extraction turned that into one field per unit, which is the same thing until something inside the tick takes a copy of its own: a shield absorbing the burn captured the shield's entry, and the burn's write-back then put the shield's fields into the burn's slot. The model, which checks that every write-back has its capture, stopped on it in one battle in eleven; the engine silently turned a burn into a second shield. One copy per entry restored the original. When a port turns locals into fields to cross a seam, check what can run between the write and the read.

Prove a slice on battles that exercise it. The reference battle in the reference port had no status tick in it at all, so "the reference battle is unchanged" proved nothing about a tick slice. What did: the same fixed set of seeded battles across the whole species table, fought on the model before the change and after it, with every event, every view call and every sound compared line by line, and every difference sorted into "intended" or "unexplained". A slice is done when the unexplained pile is empty. Two of the three defects above were found that way, not by reading code.

One identity per unit. The engine had named a unit in the event stream by its own instance id, written out in eight separate places; the headless battle named it by its deployment row. The fix is one home - the unit model's id, set to the row's once as the battle starts - and every place that needs an id asking for that one. An identity written twice is an identity that drifts.

Replace a type, keep what the engine did with it. When the engine's own copy of a type goes and the engine holds the model's instead, the model's type must keep every property the engine relied on, not only the fields. In the reference port the engine's status entry was marked serializable, which is what made the editor list a unit's statuses during play and a scene saved in play keep them; the model's twin was not, and deleting the engine's would have quietly dropped both. Its field notes move with it too, each one checked first: one note claimed a field is read, and nothing read it any more.

A script compiled in two places is checked in both. The model's headless suite compiles some of the engine's own scripts against stubs of the engine. A slice that edits one of them changes what the suite compiles after the landing, so the gate builds and tests the suite a second time with the slice's copies, in a build folder of its own. In the reference port nine landings had carried such a script past a gate that only ever compiled the live copy.

Judge a deleted type by type. A gate that compares a slice's fields file by file will read a type the slice deletes as all of its fields turned into properties, and fail on every unrelated string that shares a field's name. What a deleted type can lose is different: its own name, looked up as a string or kept in a serialized reference, and the fields that held it, whose stored values the engine may drop.

Change a recording's format behind a projection. A slice that makes the event log say more cannot be compared with the run before it line for line. Compare both runs by the columns every format carries, name a record only the new run writes as new, and fail a record only the old run wrote: a slice may add a record, never drop one. Teach every reader the new format before any writer uses it, and re-make every engine's recordings at once.

A scene object is authored, not only played. A unit exists only in a battle; a tile is painted in the editor and saved into the map. Its record stays where the map keeps it, and the battle's state is made from it when the battle starts, so playing never changes what was painted. Moving its members can change the names the engine saves them under, which changes every map file once: that is the owner's call, not the slice's.

Where the reference port stands. The order of every status landing, hit, tick and death now lives once in the Core, each engine's method a single call into it, both engines name a unit by the same id and hold one status entry type, and the event log carries every field an event has. Unity's Unit holds its UnitModel (named BattleUnit until the refactor began) and forwards its state to it: its status list, its status operations, a status leaving, its technique timers and its per-turn bookkeeping each have one home, the model's, and the battle's turns, the AI's steps and the player's commands run through the Core's flow in both engines, on the Core's dice. The rules still reach a unit through small per-topic interfaces that each engine implements; most of them wait on the board, whose saved names are the owner's call (above). Moving the rest into this shape, one topic at a time with every landing's battles compared byte for byte, is under way; a second game should port straight into it.

An example: a unit's move range

The reference port is a turn-based tactics game in the manner of XCOM: units on a grid of tiles, each turn spending action points to move and attack. Its rules lived in its MonoBehaviours. Here is one of them as the port moved it, in its extraction run on 2026-09-29: nothing below was changed for this page. The excerpts are the copy taken before the move and the code as it stands. The game's namespace is written <Game>.Core; the rest is the code as it is, shortened where it says ....

Before: the rule inside the MonoBehaviour. Unit was a MonoBehaviour of 6,837 lines before the move (5,552 after). The unit's move range was one of its methods, reading the unit's statuses and rounding through Unity's Mathf:

public int GetEffectiveMovement()
{
    // Root: cannot move at all (can still attack)
    if (IsRooted) return 0;

    int baseMoveRange = unitData.SpeciesAttributes.HorizontalMovement;
    int moveRange = baseMoveRange;
    if (ActiveStatusEffects != null)
    {
        foreach (var s in ActiveStatusEffects)
        {
            if (s.Type == StatusType.MoveDown)
                moveRange -= Mathf.RoundToInt(s.Magnitude);
            if (s.Type == StatusType.ExcessMovement)
                moveRange += Mathf.RoundToInt(s.Magnitude);
            ...
        }
    }
    ...
}

After: the same rule in the engine-free model. It moved verbatim, with two changes. The unit is reached through an interface the rule declares (self), and Mathf.RoundToInt became the model's MathRules.RoundToInt, copied from a compatibility layer proven bit for bit against Unity's own UnityEngine.dll: banker's rounding, as Unity rounds. Those two changes are the port: the rule now names no Unity type, so Unreal and the headless runner can run it too, and what it computes is the same.

public static class UnitMovementRules<TUnit> where TUnit : class, IStatContributionUnit
{
    public static int EffectiveMovement(TUnit self, IAccessoryLookup accessories, IMovementRangeHost host)
    {
        // Root: cannot move at all (can still attack)
        if (self.IsRooted) return 0;

        int baseMoveRange = self.SpeciesAttributes.HorizontalMovement;
        int moveRange = baseMoveRange;
        for (int i = 0; i < self.ActiveStatusCount; i++)
        {
            var s = self.ActiveStatusAt(i);
            if (s.Type == StatusType.MoveDown)
                moveRange -= MathRules.RoundToInt(s.Magnitude);
            if (s.Type == StatusType.ExcessMovement)
                moveRange += MathRules.RoundToInt(s.Magnitude);
            ...
        }
        ...
    }
}

What is left in Unity: one line. The MonoBehaviour keeps its public method, so nothing that calls it changes, and forwards to the rule. The warnings the rule used to log inline reach Unity's console through a small host object:

public int GetEffectiveMovement()
    => <Game>.Core.UnitMovementRules<Unit>.EffectiveMovement(
        this, UnityAccessoryLookup.Shared, UnityMovementRangeHost.Shared);

The headless runner and the Unreal host play the reference battle on the model's own unit, UnitModel, which calls the same rule, and u2ue parity compares the engines' answers bit for bit. The playbook's Step 6 (below) is this move, made for every rule.

The method, step by step

This section explains each step and shows what it produces, with real output. "The logic playbook" below runs the same work one slice at a time as DO / RUN / DONE WHEN steps, and py -m u2ue --project <game> logic judges where a port stands against them: each step here names the playbook step that runs it.

1. Inventory the code

Run as the playbook's Step 1 (read the game) and Step 2 (draw the slice's class model).

py -m u2ue --project <game> inventory --survey     # every top folder under Assets with its .cs count: name the game's own as code.roots
py -m u2ue --project <game> inventory

Per type: MonoBehaviour / ScriptableObject / plain, its lifecycle methods, every Unity call by family, and the pure rules - types that use no Unity API, which move into the model first. Partial classes are merged across their files. The reader is lexical (comments and strings blanked, a brace stack per type): a call through an alias or reflection is not seen, so a miss is unknown, never "does not use". Chapter 4 shows a full run.

A rule does value-type maths (Vector3, Mathf, Color). The inventory counts Unity's value types as a family of their own, so such a rule is not pure: its arithmetic is UnityEngine's. It does not move as written: where those types live in an engine-free model is the owner's decision, made once for the whole model ("Floats across runtimes" below has the two answers), and the rule waits for it. Branches from step 1.

Then draw the class model of the first slice before moving anything - the diagram is the plan a person reviews:

py -m u2ue --project <game> uml extract                        # the class model off the game's code roots (its own index)
py -m u2ue --project <game> uml mermaid --focus TypeA TypeB    # a slice's class diagram, every member a real one

2. Read the frame order

Run as the playbook's Step 1 (the inventory's frame-order table) and kept by its Step 8.

The same inventory lists every MonoBehaviour's script execution order (its .cs.meta executionOrder, from the file named after the class - the script Unity orders) with its lifecycle methods. Unity's frame is: Update in that order, then the coroutine phase (yield return null resumes after every Update), then LateUpdate. The order between scripts is behaviour: measured on the reference port, re-making it by hand across several engine ticks made its first Unreal host draw things a frame late.

3. Give the model Unity's runtime rules

Used by the playbook's Step 7 (events through PlaybackQueue) and Step 8 (UnityFrame, Coroutines).

u2ue/runtime/U2ue.Runtime (netstandard2.1 and net8.0, no engine reference):

type Unity's rule
UnityClock Time.deltaTime = the real step clamped to the project's Maximum Allowed Timestep, times timeScale; the unscaled step is not clamped. The maximum is the project's own: py -m u2ue --project <game> data --from ProjectSettings/TimeManager.asset --class 5 (5 is the TimeManager's YAML type id; Unity's default is 0.33333334).
Coroutines Start runs to the first yield; a coroutine started during a frame resumes after the next frame's Updates; yield return <IEnumerator> runs nested and stops with its parent; yield return <Handle> waits and resumes the same frame its target ends; Wait.Scaled / Wait.Unscaled.
UnityFrame one frame in Unity's order: Update by execution order, the coroutine phase, LateUpdate. A host calls Tick once per engine frame.
Platform.* the six platform services (below) and SeededRandom.
FloatBits float bit patterns and ULP distance (how many representable floats apart two values are), for parity digests.
PlaybackQueue<TEvent> the model resolves an action at once and appends ordered events; the host shows one per frame, only when its presenter (IPresenter<TEvent>) is idle, and takes input only when IsCaughtUp. A history that shrinks is refused.
Digest one runtime's answers to the rule cases: digestVersion=N, then key=value rows in ordinal order, floats as bits - the file u2ue parity reads.
TrailLaw Unity's TrailRenderer as measured: the points it holds each frame (TrailLaw.Point) and the drawn vertices (TrailLaw.Vertex) with the fraction width, colour and U run on. Its test replays Unity's own play-mode bake.

What a host does with it - one frame object, the game's former MonoBehaviours registered by their execution order, one call per engine frame:

using System.Collections;
using U2ue.Runtime;

var clock = new UnityClock(0.33333334f);      // the project's Maximum Allowed Timestep, READ with `u2ue data` (above)
var coroutines = new Coroutines(clock);
var frame = new UnityFrame(clock);
frame.Add("CameraRig", -100, update: rig.Update, lateUpdate: rig.LateUpdate);   // -100: its .cs.meta executionOrder
frame.Add("HudPresenter", 0, update: hud.Update);
frame.AddCoroutines(coroutines);

IEnumerator Flash() { hud.Show(); yield return Wait.Scaled(0.5f); hud.Hide(); }
coroutines.Start(Flash());

// the host's tick, once per engine frame, with the real elapsed seconds:
frame.Tick(deltaSeconds);    // clock -> every Update by order -> coroutines -> every LateUpdate

Run with two frames of 0.3 s (the snippet compiled against the library as printed, with the rig and HUD writing a line each):

show            <- Start: the coroutine runs to its first yield at once
rig update      <- frame 1: every Update, by execution order
hud update
rig late        <- 0.3 s < 0.5 s: the coroutine waits; LateUpdate
rig update      <- frame 2
hud update
hide            <- 0.6 s >= 0.5 s: resumed in the coroutine phase, after every Update
rig late

dotnet test u2ue/runtime/U2ue.Runtime.Tests holds every rule and builds on any machine. dotnet test u2ue/runtime/U2ue.Runtime.OriginTests runs a set of coroutine scripts on the reference port's measured runner and on the library and requires identical step logs; it needs that port's code on disk, so it is a separate test project that runs only where that code is.

4. Put the engine behind seams

Run as the playbook's Step 5 (the platform seam, first); the view seams are what its Step 10's host fills.

  • The platform seam: six interfaces, one engine call per member - ILog (Debug.Log), ITextAssets (Resources.Load of text), IKeyValueStore (PlayerPrefs), IFileStore (the save file), IJsonCodec<T> (JsonUtility), IRandomSource (UnityEngine.Random). "The platform seam" below has every member and the trap each one taught.
  • View seams: what the presentation asks the engine to show - for a board game, IEntityView, IHudView, ICameraDirector, IEffectPlayer and IInputSource ("The view seam" below). The model says what happened; the host decides how it looks.

5. Read the data, never retype it

Wherever the playbook's steps READ a value - the rules moved in Step 6, the cases' constants in Step 9.

py -m u2ue --project <game> data --from <scene|prefab|asset> --script <ClassName>    # or --class <id> for a built-in

Every serialized value of the matching components (nested prefab instances expanded, overrides applied, references resolved to asset paths), as JSON or a dotted TSV. "Unity serialization beats the C# initializer": the scene's value is what plays. Measured on the reference port's camera rig: it equals the hand-written reader it replaced on all 152 fields and 32 curve values.

6. Cut the model, then gate it

Run as the playbook's Step 4 (cut the Core); its gates run after every move from Step 5 on.

py -m u2ue --project <game> scaffold --name <Model> --dir <a folder outside Assets>
py -m u2ue --project <game> check --only model

scaffold writes <Model>.Core (netstandard2.1 + net8.0, referencing only U2ue.Runtime) and <Model>.Core.Tests, adds the project file's model block, builds both and runs the gates on the empty model; it never overwrites.

layer_gate refuses an engine namespace in the model and any reference outside each layer's allowed set (model.layers, inner layer first); host_gate refuses a platform member declared anywhere but the hosting folder (model.hosting: the one folder that may declare platform services, <Model>.Core/Hosting as scaffold writes it). Both run on the folders the project names (model.root, and the projects model.scan lists); layer_gate checks the model's Unreal-facing references only when model.unreal_links is set. A project with no model yet is told so.

7. Prove the rules agree across runtimes

Run as the playbook's Step 9 (Headless and UnityMono) and Step 10 (with Unreal).

Each runtime the model runs on (Unity on Mono, the Unreal host on CoreCLR, a headless test runner) writes a digest, <parity.dir>/logic-<Engine>.txt: a digestVersion=N line, then one key=value row per case with every float as its 8-hex-digit bit pattern. Unity's side needs no editor: u2ue digest run compiles the rule cases (a static method returning a Digest) twice - for CoreCLR (logic-Headless.txt) and with the project's Unity version's own Mono compiler and runtime (logic-UnityMono.txt):

py -m u2ue --project <game> digest run --entry <Ns.Cases.Build> --cases <Cases.cs>
py -m u2ue --project <game> digest faithful      # standalone Mono vs a digest the Editor wrote: on Unity 6000.3, 383 of 383 rows equal

faithful reads the project's mono.faithful block: the Unity editor whose Mono it runs, the entry point and the case sources the Editor's own runner compiled, the assemblies they reference (mono.faithful.refs), and the digest that Editor wrote (reference).

Make the cases' inputs exact on every runtime (integer arithmetic, each input written to the digest): a driver that makes its own inputs with float maths measures its own drift - on the second test game it produced 177 false differences where the rule had 2. Then:

py -m u2ue --project <game> parity
game-logic comparison - digest v1
  Headless    383 rows
  Unity       383 rows
  Unreal      383 rows
  per rule group (differing / total):
    damage_base                    27 /  144  <<<
    ...
    fpmode_fused                    8 /   36  <<<
    fpmode_stepped                  0 /   36
    ...
  DIFFERING ROWS (first 20):
    damage_base_009              Headless=40400001  Unity=40400000  Unreal=40400001
    ...
  ODD ONE OUT: Unity on 35 of 35 differing row(s)
  DIAGNOSIS: fpmode_fused differs and fpmode_stepped does NOT: an intermediate precision difference ...
  CHARACTERISED AND ALLOWED: 35 row(s), each pinned to its exact bits and to 1 ULP.
    ...
VERDICT: Headless / Unity / Unreal agree on all 383 rows except 35 characterised 1-ULP row(s), which are
         unchanged since they were measured.

That is real output, from the reference port. Every row across every runtime is compared; a difference is red unless the characterised allowance pins that exact row to its exact bits and to one ULP. Here Unity's Mono is the odd one out on every differing row - it may keep float intermediates wider than float32, which ECMA-334 (the C# language standard) permits - and the two fpmode groups prove it: the same expression written with explicit float locals agrees everywhere. Applying that fix moves Unity's own values by one ULP, so it is the game owner's call.

8. Write the hosts

Run as the playbook's Step 10 (u2ue host, which copies these templates in wire).

One thin host per engine implements the seams and drives the frame. The toolkit's Unreal templates (u2ue/templates/unreal/U2ue.Unreal, taken from the reference port's hosts with the game removed) are the starting point; copy them into the host's managed project (its C# project, Chapter 3):

template what it is
AU2ueFrameActor the actor that owns the frame: each tick hands the real step to UnityFrame (clamped by the project's own maximum step, which a subclass must supply - the default refuses). Summon it with -ExecCmds="summon /Script/UnrealSharp.<Name>_C"
UnrealPointer the cursor, its position in Unity's frame (origin bottom left), its world ray, and keys pressed or released this frame - polled before the frame runs
UnrealCameraRig one camera actor made the view target; the model's pose copied onto it, with Unity's vertical field of view converted to Unreal's horizontal one
UnrealPlatform.cs the six platform services on Unreal: the log, a manifest-backed text folder, a save-folder file store, PlayerPrefs as one file, System.Text.Json with fields, a random source with Unity's bounds

dotnet build u2ue/templates/unreal/U2ue.Unreal compiles them against a real UnrealSharp install (set U2UE_UNREALSHARP to the host's Plugins/UnrealSharp), so a template that no longer matches the engine's bindings fails there.

What the toolkit does not do here

It does not move the code for you, decide the seams, or write the hosts. It tells you what each type touches, gives the moved code Unity's runtime rules, reads the data, gates the boundary and proves the answers agree.

Topic by topic: the rest of a Unity game

The method above is the order of work; this is the map by topic: for each part of a Unity game, what Unity does, what Unreal offers, the route that was proven (on the reference port, unless the topic says otherwise; here a route is the approach that worked, not a converter route behind a switch), and what the toolkit gives today. NOT YET means the toolkit has nothing for it yet and the route is the only worked example. py -m u2ue find <words> searches this manual, the tools and the converter together; in the toolkit's own tree it also searches shared/PORTING_ANOTHER_PROJECT.md, the long form this chapter was written from, which the package does not ship.

The one decision everything else follows from

The decision at the top of this chapter. Toolkit: HAVE. py -m u2ue --project <name> check --only model runs layer_gate.py (the model references no engine - not UnityEngine, not UnrealSharp) and host_gate.py (logging, files, JSON and random numbers go through the platform seam, never a host interface) on the folders the project file names (model.root, model.layers, model.scan, model.hosting); a project with no model yet is told so. Step 6 has what each gate refuses.

The lifecycle: Awake, Start, Update, LateUpdate, OnDestroy

  • Unity: Awake and OnEnable on load, Start before the first Update, then every frame Update, the coroutines, LateUpdate, in script execution order; OnDisable and OnDestroy at teardown.
  • Unreal: an Actor's constructor, BeginPlay, Tick(deltaSeconds), EndPlay(reason). There is no LateUpdate and no coroutine phase; tick groups exist but do not mirror Unity's order.
  • Route: one actor owns the game screen. BeginPlay builds the world, Tick runs one frame object once per engine frame, EndPlay tears it down. The frame object is Unity's frame order written once - the clock, each former MonoBehaviour's Update in its order, the coroutine pass, LateUpdate - each entry citing the executionOrder it stands for, read from the .cs.meta files. Not one actor per MonoBehaviour: the order between them is the behaviour (step 2).
  • Toolkit: HAVE. u2ue inventory lists every MonoBehaviour's execution order and lifecycle methods; U2ue.Runtime.UnityFrame is the frame object (step 3).

Coroutines, WaitForSeconds, Invoke

  • Unity: StartCoroutine(IEnumerator), yield return null / WaitForSeconds, resumed after Update.
  • Unreal: latent actions, timers or async tasks. None of them resumes at Unity's point in the frame.
  • Route: keep the iterators. A small runner steps them - Start, Stop, StopAll, and Resume (the yield-null pass) - with a scaled and an unscaled wait for WaitForSeconds and WaitForSecondsRealtime. The model never waits: a rule that waited in Unity becomes a step the host advances. Do not make the model await either: that inverts control into every coroutine site, and the reference port had 833 of them.
  • ABSENT: Invoke / InvokeRepeating and FixedUpdate. The reference port uses none of them, so there is no worked example, and UnityFrame has no fixed-step phase.
  • Toolkit: HAVE. U2ue.Runtime.Coroutines (Wait.Scaled / Wait.Unscaled), held to a measured runner by dotnet test u2ue/runtime/U2ue.Runtime.OriginTests (step 3); u2ue inventory counts every type that uses coroutines.

Time

  • Unity: Time.deltaTime (scaled, and clamped by the project's Maximum Allowed Timestep), unscaledDeltaTime, timeScale.
  • Unreal: Tick's deltaSeconds, and global time dilation.
  • Route: one clock for the whole frame takes the engine's unscaled seconds each frame and derives Unity's: DeltaTime = Min(unscaled, MaximumDeltaTime) * TimeScale.
  • Toolkit: HAVE. U2ue.Runtime.UnityClock takes the project's own maximum step (read it with u2ue data --from ProjectSettings/TimeManager.asset --class 5, field Maximum Allowed Timestep; Unity's default is 0.33333334).

Random numbers

  • Unity: UnityEngine.Random, one global, unseeded stream.
  • Unreal: FMath::Rand, and random streams.
  • Route: the model asks IRandomSource. Unity's adapter (the Unity-side class that implements the seam; "The layers, as they are on disk" below calls these engine adapters) keeps the global stream, so the sequence the player sees is unchanged; headless and parity runs use a seeded System.Random. A presentation-only noise (a UI sound's samples) draws from the host's own stream, never the rules' stream.
  • Toolkit: HAVE. U2ue.Runtime.Platform.IRandomSource and SeededRandom with Unity's bounds: int Range upper-exclusive, float Range and Value inclusive at BOTH ends - measured in the editor, not taken from the documentation: 100,000,000 draws each of Unity's Random.Range(0f, 1f) and Random.value returned exactly 1 and exactly 0 several times, the smallest positive 1.19e-7. SeededRandom draws k / 2^23 for k in [0, 2^23], one draw each, so both ends come up as Unity's do (it used to draw NextDouble(), which never reaches 1). u2ue parity compares the rules' answers across runtimes.

Floats across runtimes

  • Unity runs C# on Mono; the Unreal hosts and the headless runs use CoreCLR, and the same float expression can round differently. Measured on the reference port: 35 rows, every one 1 ULP, all in one damage formula, Mono the odd one out on every row (step 7 has the run and the fix; the header of logic_diff.py records it). A second game's first slice met the same cause: its PID formula (a proportional-integral-derivative controller that steers a turn) differs by 1 ULP on 2 of 641 rows.
  • Compare floats by bit pattern, never by printed text: Mono prints 9 digits and .NET prints the shortest (FloatBits.Hex; the text difference alone once produced 230 false mismatches). Toolkit: HAVE. u2ue parity (wrapping logic_diff.py) compares every runtime's digest by float bits against a characterised allowance; U2ue.Runtime.FloatBits writes and measures bit patterns.
  • Unity's side with no Editor: u2ue digest run compiles the cases for CoreCLR and with the project's Unity version's own Mono (<editor>/Editor/Data/MonoBleedingEdge: its csc.exe and mono-bdwgc.exe). u2ue digest faithful measured that Mono run equal to the digest the Editor wrote, 383 of 383 rows on Unity 6000.3.16f1; another Unity version is UNMEASURED until its own Editor-recorded digest is compared.
  • Unity's value types in a model (Vector3, Mathf, Color; u2ue inventory counts them as their own family): where they live is one decision for the whole model, with two answers - copy each member the rules use into the model, measured bit-exact against Unity (the reference port's route), or allow a value-type library as the model's one reference, which is only as exact as its measurement (the reference port's shim UnityCompat.Core, its own copy of Unity's value types ("The shim route" below), is bit-exact on 101 of 105 members). It is the owner's call; port the float-only rules first.

Spawning and destroying: Instantiate, Destroy

  • Unity: Instantiate(prefab), Destroy(go).
  • Unreal: SpawnActor, DestroyActor; Niagara systems through UNiagaraFunctionLibrary.
  • Route: the model never spawns. It states what happened ("The event stream contract" below) and the view adapter makes or removes the engine objects: AActor.Spawn for an entity, SpawnSystemAtLocation for an effect, DestroyActor to remove one. Ask the engine whether an actor is still alive: the managed wrapper outlives DestroyActor.
  • Toolkit: effects HAVE (the converter builds the systems the player spawns). Actors: a TEMPLATE, AU2ueFrameActor in u2ue/templates/unreal/U2ue.Unreal (step 8); its headless smoke run is NOT YET (Appendix B).

Finding things: GetComponent, FindObjectOfType, singletons

  • Unity: components found at run time, often through a static Instance.
  • Unreal: components and subsystems; GetActorOfClass.
  • Route: the model is handed what it needs through host interfaces (I*Host, one per question the rules ask), so nothing searches a scene. The hosts hold their references directly.
  • Toolkit: HAVE. u2ue inventory lists, type by type, every Unity call by family (lookups among them) and the pure-rule types that use none - what moves into the model first (Chapter 4 shows the second game's run).

The transform: axes, units, rotation

  • Unity: metres; x right, y up, z forward; left-handed. Euler angles apply Z, then X, then Y.
  • Unreal: centimetres; x forward, y right, z up; also left-handed.
  • The conversion, one line each way: ue.X = -x*100, ue.Y = z*100, ue.Z = y*100, with its exact inverse. Directions: u2ue_dir(v) = (-x, z, y); rotations: u2ue_quat(q) = (-qx, qz, qy, qw) (both functions in vfxport/build_niagara.py). The ZXY Euler order was MEASURED on Unity 6000.3, not assumed. Chapter 6 has the full table.
  • A trap: a scene imported through glTF arrives in a frame the pipeline chose (Chapter 6), so a level and a hand-placed actor need not share a frame. Measure the imported level's frame once and convert every hand-placed actor through it.
  • Toolkit: HAVE. u2ue/transform.py holds every convention above, held by its selftest to the converter's own functions; its Unreal composition is READ from the engine (TransformVectorized.cpp:295-323).

The transform chain: hierarchy, scale, shear

  • Unity: a Transform composes as a 4x4 matrix, so a rotated child under a non-uniformly scaled parent is sheared.
  • Unreal: a SceneComponent holds translation, quaternion and scale. It cannot hold a shear.
  • Route: measure, do not average. Compose every node both ways and push each drawn mesh's corners through both; whether to accept, bake or fix the error is decided with its number, then pinned by a gate (Chapter 6 has the numbers). The effect converter refuses a sheared particle node and names it.
  • Toolkit: HAVE. u2ue shear --gltf <export> (or --from <scene>, which expands nested prefab instances by the effect reader's rules) lists every sheared node, whether it draws, and the error in cm under Unreal's own composition rule; on the reference port's first map it finds the same 46 nodes that were measured by hand.

Scenes and prefabs

  • Unity: .unity and .prefab YAML, .meta GUIDs, nested prefabs and overrides.
  • Unreal: levels (.umap) and Blueprint or C# actor classes.
  • Route: geometry, materials and textures go through the standard pipeline - exported from Unity with glTFast (a glTF exporter run as an Editor script), imported with Interchange (Unreal's own scene import pipeline). Inactive subtrees are skipped and listed; every value not carried is named ABSENT. scene_fidelity_gate.py re-measures hierarchy, materials, textures and placement against Unity's own files without opening either editor.
  • Toolkit: HAVE - u2ue scene (Chapter 6). The notes on reading prefab YAML (nested instances, variants, legacy prefab records) apply to any scene reader.

Inspector values, ScriptableObjects, data files

  • Unity: serialized fields on MonoBehaviours and ScriptableObjects, Resources.Load, JsonUtility.
  • Unreal: UPROPERTY defaults, data assets, data tables.
  • Route: the values are read, never retyped. JSON goes through IJsonCodec<T>; on Unreal that is System.Text.Json with IncludeFields = true, without which public fields serialise as nothing. Text assets go through ITextAssets.
  • Toolkit: HAVE. u2ue data --from <scene|prefab|asset> --script <Class> (or --class <id>) writes any component's or ScriptableObject's serialized values as JSON or TSV, nested prefab overrides applied (step 5 has its measured check).

Input

  • Unity: Input.GetKeyDown, the mouse position, Camera.ScreenPointToRay.
  • Unreal: Enhanced Input, or polling the player controller.
  • Route: polled. The IInputSource implementation uses APlayerController.WasInputKeyJustPressed and UGameplayStatics.DeprojectScreenToWorld; the pick itself is a rule of the model, not an engine trace, so both engines pick the same cell. Enhanced Input is not needed.
  • Toolkit: a TEMPLATE - UnrealPointer in u2ue/templates/unreal/U2ue.Unreal (step 8); its headless smoke run is NOT YET.

Logging, files, preferences: the platform seam

The six interfaces of step 4 - ILog, ITextAssets, IKeyValueStore, IFileStore, IJsonCodec<T>, IRandomSource - which your game implements the same way any game does; "The platform seam" below has their members and the rule each one taught. Toolkit: HAVE - the six in U2ue.Runtime.Platform, their Unreal implementations as a template (UnrealPlatform.cs in u2ue/templates/unreal/U2ue.Unreal), and u2ue check --only model refuses a platform member declared outside the hosting folder.

Camera

  • Unity: a Camera component, often driven by a controller script; Cinemachine.
  • Unreal: a CameraActor or CameraComponent made the view target.
  • Route: the camera's rules are the model's, fed the rig's serialized values (read as data, above). Unreal places a camera actor and makes it the view target with SetViewTargetWithBlend; a director class on the host carries the shots.
  • Toolkit: a TEMPLATE - UnrealCameraRig in u2ue/templates/unreal/U2ue.Unreal (step 8); its headless smoke run is NOT YET.

UI

  • Unity: a uGUI Canvas, RectTransforms, layout groups, TextMeshPro.
  • Unreal: UMG widgets, or Slate.
  • Route: not a UMG tree. The Canvas is captured, laid out by a port of uGUI's own solver and painted in one UUserWidget.OnPaint, because UnrealSharp's UWidgetTree.RootWidget is read-only and a UMG tree cannot be assembled from C#.
  • Toolkit: HAVE the layout side - U2ue.Ui, the generic uGUI / TextMeshPro library with its own tests (u2ue ui test), and u2ue ui convert. The capture needs the package's Editor assembly (Appendix B). Chapter 6 has the whole route.

Audio

  • Unity: AudioSource pools, procedural clips through AudioClip.SetData.
  • Unreal: Sound Waves, Sound Cues, MetaSounds.
  • Route: a presentation rule picks the voice and the gain as Unity's audio manager did; Unity's procedural clips are rendered to float PCM once and played through a small C++ bridge that hands the samples to the mixer unconverted, as a 2D one-shot.
  • Toolkit: the bridge as a plugin of the host template, u2ue/templates/unreal/Plugins/U2ueAudio, with a judge for its selftest's rendered tone. Its build in a host and its headless play are proven (2026-10-15); an AudioSource mapping is NOT YET (Appendix B).

Animation and physics

There is no worked example for an Animator, Animation Blueprints, Sequencer, or physics simulation: the reference port's units are painted cards whose motion is a rule of the model. ABSENT, said here so nobody reads silence as a recipe (Appendix B).

What none of this proves

A host that compiles is not a port. It is proven by the same model run on both engines and compared - py -m u2ue --project <name> parity, which wraps logic_diff.py (step 7) - and by pixels for the look.

What the field says about the model

What published engines, frameworks and their authors say about the choices this chapter makes: who owns the state, how the core tells the view what happened, and how many interfaces a boundary needs. Each claim is linked to its source, with how sure it is.

Who owns the state

The simulation owns it

The field's answer is not split.

  • Photon Quantum. The Frame is the game state. The Unity view holds none of it and uses the Frame API only to read, because writing from Unity would be non-deterministic; the view polls the frame's generated structs (link).
  • Forge. The framework owns attributes, tags, effect lifecycles, ability grants and cooldowns; engines keep no parallel state.
  • Unity's own guidance. Its testing articles and its ScriptableObject guidance push logic out of MonoBehaviour into plain C#, because a MonoBehaviour cannot be created with new, so it cannot be constructed or mocked in a test (unit testing, data and logic).

Confidence HIGH: three independent sources, one of them the engine vendor a port leaves. None has the model reading state back out of the engine object.

Role interfaces and header interfaces

Cutting a model out of engine classes tends to leave many narrow interfaces, each naming the members one collaboration needs, all implemented by the one engine-side class. Martin Fowler recommends exactly that: it is his RoleInterface, argued for against the HeaderInterface (one interface that mirrors the class), and the only cost he names is the effort of forming each role (RoleInterface). Confidence HIGH on what the page says.

So the case for collapsing them cannot be "role interfaces are bad". Two arguments survive. One is a measurement: with one production implementor nothing is segregated, and every forwarding member and generic parameter pays for a substitutability nobody uses (the reference port's first extraction, 2026-09-30: 130 interfaces, 128 of them with one implementor, and 141 members that only forwarded). The other is the sharper name: when dozens of role interfaces together enumerate the class's whole public surface, member for member, with no transformation, they add up to a header interface split many ways, which Fowler defines and recommends against (HeaderInterface). Role interfaces in construction, one header interface in aggregate explains why each decision looked right and the whole did not.

Names for the fix

Three traditions point the same way:

  • Aggregate (Eric Evans, Domain-Driven Design): one object owns a consistency boundary; outside code holds it, not its parts.
  • Humble Object: the hard-to-test environment object becomes a thin shell over a testable core. Its primary page, xunitpatterns.com, refused the connection on 2026-09-30, so it is named here, not quoted.
  • Plain-data components (Quantum's DSL, a domain-specific language; Overwatch's ECS, an entity component system; data-oriented design generally): the state is a struct, there is no interface at all, and systems run over filtered sets of structs.

The third is what the field ships: Quantum did not fix many facets with a better interface; it removed interfaces from the state model. Justify one sealed aggregate with the measured cost (generic parameters and forwarding members that serve one class), not the interface count: on count alone the literature is against you.

Plain data and systems, not interfaces

Quantum declares its game state in a DSL (.qtn files) that generates plain C# structs, attached to entities and used to filter them, for memory layout and generated serialisation and checksums, not polymorphism. There are no per-rule interfaces anywhere in its state model. Confidence HIGH, vendor documentation read directly (link).

Overwatch arrived at the same place independently: strict ECS, server-authoritative, prediction on top (Tim Ford, GDC 2017, "Overwatch Gameplay Architecture and Netcode", video, vault). Confidence MEDIUM: known from several secondary descriptions; the talk was not watched, so it is not quoted.

One aggregate interface and a cue stream

Forge (gamesmiths-guild), an engine-agnostic C# gameplay framework modelled on Unreal's Gameplay Ability System (netstandard2.1 and .NET 8, claiming Unity, Godot and other C# engines), integrates through ONE interface, IForgeEntity (attributes, tags, effects, abilities, events, shared variables), and presents through a "Cues" event system. The framework owns the state; the engine reads it (link). Confidence LOW as proof (32 stars, a README that calls it a work in progress, no multiplayer), HIGH as a data point about shape: someone solving the same problem arrived at one aggregate interface and a cue stream.

How the core tells the view what happened

"The simulation emits events and the view interprets them" is the standard answer, but the field never uses events alone. Two independent shipped systems - one commercial middleware, the other Epic's own framework inside the engine a port moves to - describe the same three-part split.

Poll, events, commands

Poll anything continuous. Quantum's guidance is that polling the simulation from Unity is generally preferable for ongoing visuals, and events are for one-off occurrences. Polling suits values that change often, and a late joiner gets everything it needs from the game state.

Events for one-off occurrences, with their unreliability documented. Quantum events are fire-and-forget, flow from the simulation to the view, and must never change game state; a late joiner does not receive events raised before it joined, and the entity view an event targets may already be destroyed. Epic says the same of Gameplay Cues (the Gameplay Ability System documentation for UE 5.8, read 2026-09-30): they run visual and sound effects and do not use reliable replication, so a client may never receive one, and tying gameplay code to them causes desyncs (link).

Address effects by tag, not by call. This is the part worth copying. A Gameplay Cue is not called: it is associated with Gameplay Tags, and any Gameplay Effect that matches those tags applies it. The simulation applies an effect carrying a tag; the presentation registers handlers against tags; no simulation code names a presentation function.

Commands for the direction that needs an answer, and never synchronous. Quantum Commands carry input from the view into the simulation as DeterministicCommand objects, consumed by the simulation on a later tick that a remote client cannot predict (link). The view asks; the simulation acts on a later frame; nothing blocks.

Confidence HIGH: two independent vendors, both primary documentation, read verbatim, saying the same three things.

Where events break

  • Rollback duplicates events. A frame simulated more than once (prediction, rollback) raises its events more than once. Quantum drops duplicates by a hash over the event's data (nothashed marks the members left out of it) and offers a synced keyword that holds an event until the server confirms the frame.
  • Anything built from events cannot be rebuilt on a late join, a reconnect, a save and load, or a replay scrub.
  • The general form. Fowler, on Event Sourcing: events that send updates to external systems go wrong on replay, because those systems cannot tell replay from real processing; his fix is a Gateway that checks for replay mode before passing a call out (link).

Confidence HIGH on Fowler (primary, read directly) and on Quantum (vendor documentation, read verbatim). A callback from the model into the engine is this general form: a call to an external system that a replay will repeat.

What really needs a synchronous answer

As far as the research could find evidence, fewer things than it seems, and they split two ways:

  • "Can this move?" is a QUERY on the model, not a call into the view. It is a callback only while the state still lives in the engine object; moving the state into the model dissolves it. Keeping queries apart from state-changing commands is CQRS (link), cited as a name, not as game-specific evidence.
  • "Did the player confirm?" is a COMMAND that arrives later, as Quantum's do, processed on a later tick. A playback queue between the model and the host is what makes that possible.

The line for a port: everything shaped "something happened, show it" becomes a tagged event with handlers registered by tag on each engine, which is Epic's own answer inside Unreal; everything continuous is polled off the model; and the residue that truly needs an answer is counted only after the state has moved into the model.

How many ports

Alistair Cockburn calls what is and is not a port in a hexagonal architecture largely a matter of taste: one port per use case would give hundreds, merging them all would give two, and his own choice tends to two, three or four. In the same paragraph he adds that there seems to be no particular damage in choosing the "wrong" number (link). He does not say a high port count is harmful.

Count ports properly: a port is a boundary to an external technology. A model's view seams and platform services ("The model in depth" below) are ports; interfaces the model uses to read its own state are a coupling problem, not a port count. Counted that way, a presentation seam of a few interfaces sits inside his range, and the overshoot is the callbacks from the model into the engine. Confidence VERY HIGH on Cockburn's words, read on the day; the recount is the research's analysis.

One implementor per interface

  • The Reused Abstractions Principle (Jason Gorman): an interface with only one implementation is a code smell. Gorman's own posts returned HTTP 500 on every attempt and were not read. The verified anchor is Mark Seemann, "Interfaces are not abstractions" (2010-12-02), which credits the principle and describes header interfaces as stating the same thing twice (link).
  • The honest counter: Ted Kaminski defends single-implementation interfaces because they cut off transitive dependencies, a benefit that disappears when the interface and its only implementation share a module (link).

So look at where they live. Interfaces in the model's assembly whose one implementor - a MonoBehaviour - lives in the Unity assembly cut a real assembly boundary, which is exactly why the model need not reference UnityEngine. The case for one aggregate is not that they do nothing; it is that one interface cuts the same boundary for a fraction of the price. Confidence HIGH on Seemann and Kaminski (both read directly), MEDIUM on the principle itself (its primary text was not reachable).

Pass-through layers

  • Architecture Sinkhole antipattern (Mark Richards and Neal Ford, Fundamentals of Software Architecture): requests that pass through layers with no business logic applied; Richards' rule of thumb tolerates about 20 % pass-through traffic. The O'Reilly chapter returned 403 and was not read; this is a secondary restatement that cites them (link). A layer that is 100 % pass-through (the reference port's 141 of 141 forwarding members) is five times the tolerated ratio.
  • Middle Man, and its fix Remove Middle Man (Fowler), are the class-level names (link), with the catalogue's own caveat: a middle man made on purpose to cut dependencies, or a Proxy or Decorator, is legitimate.
  • Speculative Generality (Fowler and Beck) is the name for the motive.
  • The sharpest operational test is Aleksey Kladov's "Concrete Abstraction" (2020-08-15): if every call site uses a concrete type, you do not need the abstraction; his case study deleted 124 lines (link). Measure it: count how many of the model's generic type parameters are ever instantiated, outside test doubles, with anything but the one engine-side class. Zero is the whole argument.

Abstraction as speculation

Robert Nystrom, Game Programming Patterns: every layer of abstraction is a bet that the flexibility will be needed; abstractions everywhere make code slow to trace; and modularity that does not turn out useful becomes actively harmful (link). Sandi Metz, "The Wrong Abstraction" (2016): duplication is far cheaper than the wrong abstraction (link). Confidence HIGH that these are the arguments and their sources; both are qualitative, with no measurements.

The performance argument does not apply

Casey Muratori's "Clean Code, Horrible Performance" measures roughly 1.5x from dropping polymorphism and up to about 15x with table-driven rewrites (link), and Mike Acton's CppCon 2014 keynote (video) is a console-engine performance argument. A turn-based rules core that resolves a whole turn at once is not a hot loop: these are bad reasons to collapse a model's interfaces, and should be called bad rather than accepted as a free win.

What the prior art says to do in a port

The lessons above, and Chapter 14's on determinism, as one list in the order to act on them:

  • Settle the motive in writing first (Appendix D, "Test the motive"). It is the only finding that can invalidate a plan rather than adjust it: if the second engine came off the roadmap tomorrow, would the extraction still be worth finishing? If not, the plan rests on one community plugin, tried in one application, with no published case of an engine-free core making a real port cheap.
  • Make byte identity a tripwire, and name the real contract. Neither ECMA-334 nor ECMA-335 promises it, and two JITs are two compilers (Chapter 14, "What the standards allow"). Make the contract the same ordered events with the same identities and values, floats compared to a stated tolerance, and keep the bit-for-bit checksum as the strict check that fires first.
  • Run the explicit-cast experiment before spending anything else on drift: (float)((float)(a * b) / c) against a * b / c, since conv.r4 (the explicit conversion a float cast compiles to) must discard extra precision. Expect it to rule out fused multiply-add, because RyuJIT (.NET's just-in-time compiler) refuses to contract a*b+c and .NET has no fast-math mode; Mono's float32-as-double arithmetic is the better suspect (Chapter 14, "Fused multiply-add, and Mono's float32"; step 7's two fpmode groups are this experiment).
  • Audit the model for the two known non-rounding divergences: any float-to-int cast (undefined on Mono) and any System.Math or MathF call other than Sqrt (measured to differ between operating systems on one .NET build). Both are likelier, larger and cheaper to find than a ULP (Chapter 14, "Two divergences that are not rounding").
  • Guard against what actually desynced shipped games: ambiguous sort comparators, iteration order over hash containers, random-call-count discipline, and number-to-string formatting inside the model (1e-05 against 1e-005). A checksum catches these after the fact; a guard names them (Chapter 14, "What desynced shipped games").
  • Address presentation events by tag, not by method name (Gameplay Cues, above). Events that carry an identifier give a third engine a registry to fill rather than a list of members to implement; converting N callbacks into N named event types moves the problem without solving it.
  • Give those events the three properties the field says they need: cosmetic only, droppable, and rebuildable from state ("Where events break"). The late-joiner rule and the replay rule are the same rule, and it bites on save and load and on scrubbing a replay even in a game with no multiplayer.
  • Sort the callbacks by shape before converting any: punctual (an event), continuous (the view polls it off the model), and needs-an-answer (a query on the model, or a command answered on a later tick). Count the needs-an-answer residue only after the state has moved into the model; counted earlier, callbacks look more necessary than they are.
  • Argue an interface collapse with the sharper names: a header interface in aggregate, the sinkhole ratio, and the count of generic instantiations - and keep Kaminski's defence in view, so the refactor does not throw away interfaces that cut a real assembly boundary.
  • Write the presentation gaps on the second engine down as a feature matrix, as the READMEs of Spine (animation middleware with a Unity and an Unreal runtime, Appendix D) do, not as a to-do list.
  • Decide whether consoles are in scope, because it has an architectural consequence today (Appendix D, "Platforms").

The logic playbook: the u2ue-logic skill in full

Everything that is not logic ports itself: the effects through the u2ue-port skill, scenes through u2ue scene, screens through u2ue ui, data through u2ue data. Logic is the one part a person or an AI model ports by hand. This section is the method above as the skill file u2ue/skill/u2ue-logic/SKILL.md holds it, one slice at a time: each step with the command that runs it and the observable that says it is done, pointing back to the method or a topic for the background. Chapter 15 covers running it with an AI agent over a long port.

The acceptance test: the game's rules run in ONE engine-free model; Unity, the Unreal host and a headless runner give the same bits for every case (u2ue parity exits 0); and the game as the owner plays it still works.

Scope: a Unity game's C# - its MonoBehaviours, coroutines and frame order - and the engine-free model it moves into. Precondition: the game's Unity project is on disk serialized as text, and a project file names it. Stakeholders: the porter wants the game running on Unreal, the same; the owner wants only their decisions asked; a reviewer wants the design reviewable from its class model, not line by line. Minimal guarantee: nothing is invented - a rule that cannot move is named with its reason, and a red gate stops the step. Success guarantee: the rules run in one model, Unity's runtime and the Unreal host give the same bits, and the game still plays.

Kickoff prompt

The owner pastes this to an agent, with the two names filled in:

Port the logic of the Unity game at <UNITY PROJECT ROOT> with u2ue, project name <name>. Follow the u2ue-logic skill step by step. One slice at a time, smallest first. Do every step's RUN, and do not start the next step until its DONE WHEN is true. Draw the class model before moving code. Ask me only for the decisions the skill names as the owner's.

The bones: each concept one thing

The analogy is the handle; the class is the truth.

  • Project (u2ue/projects/<name>.json) - the game's address book: every path, named once.
  • Inventory (u2ue inventory) - the survey of the house before the move: every type, what it touches in Unity, which are already furniture that moves as it is (pure rules), and the order the rooms are walked in each frame.
  • Core (<Model>.Core, made by u2ue scaffold) - the rulebook: what happens, never how it looks. No engine in it.
  • Aggregate - ONE class per entity holds its state (a unit, a card, a board); the engine's object HOLDS one and forwards to it. Never forty little interfaces over one MonoBehaviour: the shape adds code and makes nothing testable ("What a second game writes" has the measurement). This is the Model of the u2ue-mvc skill, "MVC: the shape the logic moves into" above (<Thing>Model). Holding and forwarding is the safe first step; the end shape is a View that holds only the Model's id, with one Controller per scene owning the Models.
  • Seam - the plug sockets: the platform seam (logging, files, preferences, JSON, random numbers - U2ue.Runtime.Platform), the view seam (what draws), the capability seam (optional extras on top of the view seam, "The interface set" below). An engine implements a seam; the Core declares it.
  • Event stream - the referee's call sheet: rules resolve a whole action INSTANTLY and append ordered events. The model never waits.
  • PlaybackQueue (U2ue.Runtime.PlaybackQueue<TEvent>) - the replay operator: one event per frame, only when the view is idle; input waits for IsCaughtUp.
  • UnityFrame (U2ue.Runtime.UnityFrame with Coroutines and UnityClock) - Unity's frame order (Update by execution order, the coroutine phase, LateUpdate) as one object an engine ticks once per frame.
  • Digest (U2ue.Runtime.Digest) - one engine's answer sheet; parity (u2ue parity) marks the sheets against each other, bit for bit.
  • Host - the engine's side: a Unity MonoBehaviour or an Unreal actor that holds the aggregate, feeds input and presents events.

The law of the playbook

It overrides speed and tidiness:

  • READ or ABSENT - a value in the model comes from the game's code or data, with where it came from; never a plausible constant.
  • No fallbacks - a rule that cannot resolve throws and names what is missing; catch {} and a default are the same lie.
  • Move, do not rewrite - the rule's code moves into the Core as it is; a behaviour change is a separate, named decision.
  • The model knows no engine - u2ue check --only model after every move; a red gate stops the move.
  • A check that has only passed proves nothing - every gate here has a plant it must fail (--selftest); run it once.
  • The owner's editors are the owner's - never the Unity Test Runner; Unity runs only in a window the owner allows; one headless Unreal at a time; never a modal answered for them.

The playbook's steps

Each step has a DO (what to do), a RUN (the command; every one exists and runs, and skill_gate.py checks that) and a DONE WHEN (the observable that ends it). py -m u2ue --project <name> logic judges each step's DONE WHEN from the records and says where a port stands.

Before you start: name the project

  • Do: write u2ue/projects/<name>.json from the complete example in Chapter 3, and fill in the Unity root, its version and the work folders. For a port already under way, ask where it stands first and resume at the step it names next - never re-derive the state from the files.
  • Run: py -m u2ue --project <name> info, then py -m u2ue --project <name> logic.
  • Done when: info exits 0 - every path it names opened.

Step 1. Read the game before touching it

  • Do: survey the Assets folders, name the game's OWN code folders as code.roots (vendor packages live in Assets too - never guess which are the game's), then inventory them. Read inventory.md: the pure-rule types, each MonoBehaviour's Unity families, the frame-order table.
  • Run: py -m u2ue --project <name> inventory --survey, then py -m u2ue --project <name> inventory.
  • Done when: inventory.json lists every type with its kind, and you can name the ten purest types and the five heaviest Unity users.
  • Trap: the reader is lexical - a call through reflection or a helper is not seen; a miss is UNKNOWN, never "does not use".
  • Trap: "pure" means no Unity API AND no Unity value type: a rule that does Vector3 maths cannot move as written (the method's step 1).

Step 2. Draw the class model of ONE slice before moving anything

  • Do: pick the first slice - one feature whose rules use the fewest Unity families (a damage formula, a scoring rule, an inventory stack). Extract the class model over the game's code roots, draw the slice's types, and write the TARGET diagram in the shape "MVC: the shape the logic moves into" names: which types become Models, which become Views, which seams appear. The diagram is the plan a person reviews; the code follows it.
  • Run: py -m u2ue --project <name> uml extract, then py -m u2ue --project <name> uml mermaid --focus <TypeA> <TypeB>.
  • Done when: the slice's current and target diagrams exist, and every name in them resolves (uml where <Name>).

Step 3. Sort the slice's types and members

  • Do: give every type in the slice ONE destination - CORE (a pure rule: it moves as it is), AGGREGATE (the state and rules inside a MonoBehaviour: they move into one Core class the MonoBehaviour then holds), HOST (what only an engine can do: draw, play, read input) or SEAM (a platform chore). Label each member the host keeps by its kind - PUNCTUAL, ONGOING, MUTATION, ANSWER or CONTROL (the table in "What a second game writes" says what each one is and what it costs an engine). In MVC's names: a CORE type becomes Rules or a Model, an AGGREGATE a <Thing>Model its MonoBehaviour's <Thing>View shows, a HOST a View or part of the scene's Controller ("Sorting every MonoBehaviour" above decides which).
  • Run: py -m u2ue --project <name> inventory.
  • Done when: the target diagram carries every type's destination and every kept host member's kind.
  • Absent: a host-kind census for any game's model. Label by hand by the rule above: a non-void member is an ANSWER.

Step 4. Cut the Core

  • Do: create the engine-free model OUTSIDE the Unity Assets tree, declared in the project file.
  • Run: py -m u2ue --project <name> scaffold --name <Model> --dir <folder>.
  • Done when: scaffold exits 0 - both projects build and the model gates PASS on the empty Core.

Step 5. Put the platform seam in first

  • Do: every log line, file read, preference, JSON document and random draw the slice makes goes through U2ue.Runtime.Platform (ILog, ITextAssets, IKeyValueStore, IFileStore, IJsonCodec<T>, IRandomSource / SeededRandom) - never re-declared on a rule's host. The reference port found a log line declared on five hosts and a random draw on seven before it did this.
  • Run: py -m u2ue --project <name> check --only model, then dotnet test u2ue/runtime/U2ue.Runtime.Tests.
  • Done when: host_gate PASSES and no rule in the slice calls Debug.Log, Random, PlayerPrefs, File or JsonUtility directly.

Step 6. Move the slice's rules into the Core

  • Do: move the code (do not rewrite it) into the aggregate; the MonoBehaviour now holds one aggregate and forwards its properties to it, so state has one home. A rule that waited (a coroutine, WaitForSeconds) becomes a step the host advances - the model never awaits. A rule doing Unity value-type maths (Vector3, Mathf) waits for the owner's one decision ("Floats across runtimes" above); take the float-only rules first. Write one test per moved rule in <Model>.Core.Tests, with the value the Unity build gives.
  • Run: py -m u2ue --project <name> check --only model, then dotnet test <Model>.Core.Tests.
  • Done when: both gates PASS, the slice's tests pass, and the Unity project still compiles with the MonoBehaviour holding the aggregate.

Step 7. Emit events; replay them

  • Do: each rule that changes what the player sees appends an event to an ordered, append-only list instead of calling the view. The host replays the list through PlaybackQueue<TEvent> with a presenter that is idle when its animation ends; input is taken only when IsCaughtUp.
  • Run: dotnet test u2ue/runtime/U2ue.Runtime.Tests, then dotnet test <Model>.Core.Tests.
  • Done when: a test runs the slice's action headlessly and asserts the event list, in order.

Step 8. Keep Unity's frame order

  • Do: per-frame code the slice keeps (Update, LateUpdate, coroutines) registers with ONE UnityFrame in its script execution order (the inventory's frame-order table, read from the .cs.meta files); coroutines run on U2ue.Runtime.Coroutines. Never one engine tick per former MonoBehaviour - the order between them IS the behaviour.
  • Run: py -m u2ue --project <name> inventory, then dotnet test u2ue/runtime/U2ue.Runtime.Tests.
  • Done when: every kept per-frame method is registered with the order the inventory lists for its type.

Step 9. Prove it: the same answers, by the bit

  • Do: write the slice's cases ONCE, as a static method returning a Digest (no NUnit in that file), driving the moved rules the way the game drives them (its own constants, READ with file and line). u2ue digest run compiles them twice - for CoreCLR (Headless: what an Unreal host runs) and for the project's Unity version's OWN Mono (UnityMono: no Editor opens) - and writes both sheets into parity.dir. Bump the digest's version whenever the case set changes.
  • Run: py -m u2ue --project <name> digest run --entry <Ns.Cases.Build> --cases <Cases.cs>, then py -m u2ue --project <name> parity.
  • Done when: parity exits 0 across Headless and UnityMono, and any characterised row (parity --characterise) carries its measured cause.
  • Trap: the cases' INPUTS must be exact on every runtime - make them by integer arithmetic and write each one to the sheet (_in rows). Measured on the second game's first slice: a driver that made its own target angles with float maths produced 177 false differences in 321 rows; with exact inputs the rule's true difference was 2 rows.
  • Trap: UnityMono is Unity's runtime, not the Editor. u2ue digest faithful measures one against the other on an Editor-recorded digest (Unity 6000.3: 383 of 383 rows identical); a Unity version without that measurement is labelled UNMEASURED in the provenance, and its Mono answer is not called the Editor's.

Step 10. The Unreal host

  • Do: the game gets its OWN .uproject, made by u2ue host the way a customer makes one: name it in the project file's unreal.host block (the template, each plugin with its source and pinned commit, the AutoSDK root, the digest's entry and cases), then run the steps in order from native PowerShell - the Unreal steps refuse while an Unreal runs, and each step is judged by its proof line, never by an exit code. wire references <Model>.Core, compiles the digest cases in, COPIES the toolkit's Unreal templates into the managed project (u2ue/templates/unreal/U2ue.Unreal: AU2ueFrameActor, which ticks UnityFrame, UnrealPointer, UnrealCameraRig and UnrealPlatform.cs; the method's step 8) and writes the module that answers the digest; run starts the host headless, and it writes logic-Unreal.txt from the same cases. Grow the host from there: it holds the aggregate and presents events through PlaybackQueue.
  • Run: py -m u2ue --project <name> host plan; py -m u2ue --project <name> host create (then install, compile, generate, wire, publish, run, one at a time); py -m u2ue --project <name> host status; dotnet build u2ue/templates/unreal/U2ue.Unreal.
  • Run: py -m u2ue.seam --project <name> --list names every seam the model declares that no model type fills and the Unreal host does not fill yet (the project's model.hosts says where each engine's host code is) - each a socket to implement, or one the host says it leaves out, and why.
  • Run: py -m u2ue --project <name> parity --require Unreal.
  • Done when: parity exits 0 across Headless, Unity and Unreal.
  • Measured: a second game's host was made this way from nothing in 9 minutes (the compile 255 s), and its digest equalled the headless CoreCLR one byte for byte. Absent: a generic publish proof by the loaded assembly's MVID (the module version id in a .NET assembly's metadata, G6 below); until it lands, run proves the host ran THIS publish only by the digest it wrote after the start.

Step 11. Record the slice and take the next one

  • Do: land the slice (slice land): its landing record (<work.records>/slice/landing-<stamp>/landing.json - the overlay, the seed and battle, the comparison and its verdict, the model's commit) is the slice's record, and logic reads it there; put the slice's first commit beside it in your notes (the tempo), and take the next slice, bigger. Each slice's diagram joins the game's model.
  • Run: py -m u2ue --project <name> check --only model.
  • Done when: the record names both commits and the parity verdict, and the next slice is chosen.

When to stop and ask the owner

A behaviour change a rule would need (a bug the port would fix), where Unity's value types live for the Core, where the game's Unreal host lives, anything that would run in the owner's live editor, and anything outward-facing. Ask one precise question, and take the next slice meanwhile.

The model in depth: what a second game implements

This section is the architecture your game's model implements - the layers, the seams and the contract between them - as rules, each with the reference port's version as its worked example. Implementing the adapters is your work; a port is not finished until a person PLAYS the Unreal build, attended.

Three things to read before the rest:

  • Read the gates (below) before the recipe. A green summary that was not measured is the exact failure the gates exist to catch: byte-identical means cmp exit 0, quoted, never a summary.
  • The event stream is half the seam. The interfaces say what an engine must implement; the stream says what the model must tell it. Measured on the reference port: most early drawing faults were the model leaving something unsaid, or saying it twice, while every interface was implemented correctly and the picture was still wrong.
  • The shim is not the architecture. Emulating namespace UnityEngine (a shim such as the reference port's UnityCompat.Core and UnityCompat.Engine) lets Unity-shaped code compile anywhere, but your game should not build its model on it ("The shim route" below says why).

The layers, as they are on disk

  • The Core is the engine-free model. Its project file holds no Reference, ProjectReference or PackageReference that leads to an engine - scaffold makes one whose only reference is U2ue.Runtime, itself engine-free - and that emptiness is the whole design: there is nothing for an engine to arrive through. It is multi-targeted for every host (scaffold writes netstandard2.1;net8.0), so one assembly serves Unity as a managed plugin, the headless suites and UnrealSharp. The model is (state, seed) -> state. It never waits: a grep for yield return or yield break over its sources must count 0 (an IEnumerator in a comment is prose). Check that with a search, not memory.
  • The platform seam is the six interfaces of U2ue.Runtime.Platform, declared once ("The platform seam" below); a domain host (one of the I*Host interfaces of "Finding things" above) declares only domain callbacks.
  • The presentation layer is the view seam: the view interfaces plus the replay that drives them (PlaybackQueue, the board as shown, one format for view calls). It references the Core and never the reverse. Every method is a GAME VERB (Place(id, cell)), never an engine primitive.
  • The engine adapters, one set per engine: the entity view, camera director, effect player and input source, and the six platform services (on Unreal, the template's UnrealPlatform.cs).

The interface set

The BASE set your game implements is five view interfaces (the four a board needs, plus IHudView) and six platform services. On top sits the optional capability seam: interfaces an engine implements when it draws more of the game than the base calls say. Every other interface in a model is a domain host or a facet of that game's rules, and your game declares its own, because they are its rules.

The view seam

The reference port's view interfaces are the worked example; the rules they follow are what transfers.

  • IEntityView draws the world. Every call is a statement about what the player should now see, never a question: spawn, place (no travel), move (the view owns the duration and the path's shape), show a health change with the HP remaining, kill, despawn (removal with no death), and an IsIdle. There is deliberately no IUnitView and no ITileView: Unity spawns a GameObject per entity while Unreal can draw tiles as instanced meshes, both satisfy one interface, and the model never learns which. If a new entity kind forces a new method, the abstraction has drifted and the fix belongs in this interface, not in another.
  • ICameraDirector frames the action: play a beat on a focus entity, and an IsIdle. The model NEVER mentions a beat: the presentation derives beats from the event stream, which is what frees Unreal to use Sequencer and look nothing like Unity.
  • IEffectPlayer is effects and sound together, because an impact is a flash AND a thud, and splitting them makes every caller coordinate two things that always fire together. Its effectKey names the effect in the GAME's vocabulary, never an engine asset path; the adapter maps it to a Shuriken system or a Niagara asset, and that mapping is the one place the two engines may disagree about what an effect looks like.
  • IInputSource is the only way anything reaches the model, and it is pull-based on purpose: a push callback would run the model from inside an engine's input handler, the inversion the event stream exists to avoid. Its commands are GAME verbs, and the command type lives in the Core, because a command the model consumes cannot live above the model. A verb like "select cell" or "confirm" describes a mouse, not the game.
  • One object is all an adapter hands over (the reference port's PresentationHost): the entities, camera, effects and input views, an optional HUD (none for a headless run), and an IsIdle that ANDs the idling views. One object beats five constructor parameters threaded everywhere.
  • IHudView draws the HUD from the board AS SHOWN (the reference port's ShownState), and is handed nothing else. The replay (there, its PlaybackQueue) calls it after the initial board and after every event it shows, at the pace of the view calls, so the HUD is never ahead of the animation. It cannot show the verdict while the killing blow is still in flight - which is exactly what a HUD bound to the model would do, because the model resolves a whole turn instantly. The HUD is not part of IsIdle: it owes no animation, so the replay never waits on it.
  • One recorder both engines and the headless suite use: a view double that writes one line per view call. Beats are derived in the replay itself; there is no separate beat-policy interface.

The capability seam

The base calls say WHAT happened; they cannot say how Unity paces and frames it (a settle before an effect, a zoom on a target, a cutscene's flight, a banner's wait). Porting those rules engine-free leaves three decisions:

  • The replay (PlaybackQueue) stays ONE switch. It never forks per engine. For each optional surface it tests the host's view with is against that surface's interface; a view that is not one gets the BASE call instead (a PlayBeat, a Play), exactly what it got before the capability existed.
  • The recorder (the reference port's RecordingView) records "the base call it replaces, or nothing". Alone (the headless suite) it answers as a view WITHOUT the capability; wrapped around a drawing view it forwards, and a drawing view that LACKS a capability makes it THROW - never a silent skip. So a run shown through the capability path records line for line what the base path records, and no recorded stream moves when a capability lands.
  • One frame object owns the one-tick order and ONE clock (Unity's frame, as UnityFrame holds it), so an adapter is a per-tick COPIER of engine-free state plus a click source.

A capability extends one base view (the entity view, the camera director, the effect player or IHudView) and records what its base call records. A new surface gets its own READ record (one data file per surface), never new lines in an existing slice, so a recording made before the surface existed stays valid.

The platform seam

These six are what any game implements the SAME WAY; that is the test for belonging here. The toolkit ships them as U2ue.Runtime.Platform:

interface members the rule its implementations taught
ILog void Info(string), void Warn(string), void Error(string) a three-level log is the smallest complete logging seam, even before anything calls ILog.Error
ITextAssets string LoadText(string resourcePath) NULL is the ABSENT signal and the only one; an existing but empty asset returns "" and parses as zero rows. On Unreal, resolve a carried text through the copy's manifest, never by guessing an extension
IKeyValueStore int GetInt(string,int), void SetInt(string,int), string GetString(string,string), void SetString(string,string), void DeleteKey(string), void Save() PlayerPrefs' own flush semantics: Set changes memory, Save writes the file
IFileStore string RootPath { get; }, bool DirectoryExists(string), void CreateDirectory(string), bool FileExists(string), string ReadAllText(string), void WriteAllText(string,string) a platform seam must not name a Unity folder (RootPath, not StreamingAssetsPath). Shipped data and save data are two stores, because one root cannot be both
IJsonCodec<T> string ToJson(T), T FromJson(string) on Unreal, System.Text.Json with IncludeFields = true - that option is the whole implementation: without it a game's fields serialise to {}
IRandomSource float Value(), int Range(int minInclusive, int maxExclusive), float Range(float minInclusive, float maxInclusive) the two Range overloads have DIFFERENT bounds, as Unity's do (int upper-exclusive, float both-inclusive), and getting that wrong compiles perfectly

Three more rules from the random source:

  • A seeded System.Random was measured bit-identical across Mono 6.13, .NET 8.0.22 and .NET 10.0.12 (the reference port, 2026-09-27), which is why one seed is one game on all three runtimes.
  • Keep the game rules' stream private to the model's own SeededRandom, and give the host's random service only to what is NOT the rules; handing the rules a host stream would end the byte-identical event log. A Value() meant to reach the float overload's inclusive maximum cannot be built on NextDouble(), which is [0, 1); the template's UnrealRandomSource returns Next(0, 1 << 24) / (float)((1 << 24) - 1). Unreal's own FMath::Rand is not in UnrealSharp's managed glue, so System.Random is the runtime's own there.
  • IRandomSource is the member that proves the seam is worth having: before the seam, the reference port declared the same draw on several domain hosts under different names (step 5's count). host_gate.py refuses every one of those names outside the hosting folder, so the leak cannot come back under a new spelling.

The event stream contract: what the model must SAY

The view interfaces are the engine's half of the seam. The other half is the model's event list: ordered, append-only, written through one sink, read by PlaybackQueue, which turns it into view calls at the view's pace. An engine draws ONLY what the stream says, so everything a player must see has to be said, once, with what a view needs to draw it. On the reference port a headless suite that plays every authored action on a test board went looking for violations and found eleven classes of them - every one the model's, not an adapter's. These rules fixed them, and your model should be held to them from its first event:

  • Every HP change is announced, with the HP LEFT - the delta and the remainder, because a health bar needs both. Silent writes are the trap (damage over time, reflected damage, an aura's victims, an action's own HP price). The check: every step's HP difference must be the stream's last word on it.
  • A status's tick is ONE announcement, its only HP event; the damage inside it says nothing more, or the same HP drops twice. A tick that moved no HP shows no number.
  • Every effect event names the square its effect plays on. An event left at the default cell asks for its effect at the board's origin and nothing else fails, so it is invisible until someone looks. That happened four separate times.
  • What a HUD shows is announced, not inferred: an action-point change with its delta and total, from ONE sweep in the flow, not from each place that writes it; a status leaving, one event per entry, from the one method entries leave through.
  • A unit an action moves is announced like a walk. A move the stream never states leaves the unit's view on the wrong square until its next walk.
  • Say each fact in ONE layer, and choose that layer on day one. A fact said in two layers makes the presenter tell the copies apart; a model that says each once needs no dedupe rules.
  • Durations are what the entry was GIVEN after every rule that touched it, not the authored number.
  • An end-of-turn tick of an action is its own event, and names the action. Whether a tick SHOWS anything is the presentation's decision, never the model's.

What it costs to check: the suite turns each rule into an expectation over every case, and each is proven able to fail by a planted fault. One was VACUOUS until a case existed that moves a unit - a gate that has only ever passed cannot be told from one switched off. Copy the suite's shape, not just the rules.

The recipe a second game follows

The playbook above is the order of work for one slice; this recipe is the order for the adapters around the model, with what each step guards against.

Step 1 - write the Core (the playbook's step 4): model state and rules only, no engine reference. Do not trust yourself about a stray using UnityEngine or using UnrealSharp, or an engine build that source-links .cs files out of another engine's tree: layer_gate.py checks both (G1 below), and its --selftest must FAIL on a planted using and a planted <Compile Include> before a PASS means anything.

Step 2 - cut the platform seam FIRST, not last (the playbook's step 5). Every log line, file, preference, JSON document or random draw declared on a domain host is surface a second engine has to implement again. Give host_gate.py your member names.

Step 3 - the engine class PRESENTS events; it never sequences a turn. This is the step that most looks like the old code and most must not be. The flow is INSTANT: it takes state and a seed, runs the whole action, and appends an ordered, immutable event list. The ENGINE ADAPTER owns a PlaybackQueue: the queue accepts the list (Accept), shows one event per frame into the views (Tick()), and exposes its Backlog and IsCaughtUp. Input is GATED on IsCaughtUp, so a player cannot act into an animation they have not seen; the adapter's IInputSource builds the commands, and the queue asks for one only once the views are idle. Three measured reasons this is not negotiable: a (state, seed) -> state model is why the reference port's Unreal side could run a whole game with no world at all; awaiting inverts control into every coroutine site; and different effect lengths per engine would otherwise take different code paths per engine.

Step 4 - write ONE adapter and prove it headlessly before writing a second. A view double prints one line per view call; that printed slice is the artifact everything else diffs against, so write it before any engine is involved.

Step 5 - write the second adapter and diff the slices byte for byte. Not "looks the same": cmp exit 0.

Step 6 - keep the model as a compiled artifact both engines LOAD, and prove the artifact is the one they loaded. This catches the failure nobody sees: an engine running a two-day-old model and producing a beautiful, stale, byte-identical artifact. Measured on the reference port, both engines did it with nothing saying so - Unity's plugin DLLs left stale, and Unreal's made stale minutes after a clean publish by an edit to the model's source. G4 (plugin_sync_gate.py) and G6 below catch it. Run G4 at the start of every session as well: a model source newer than the DLL an engine loads is the stale state, found before anything is built on it.

Step 7 - know what your reference checksum does NOT cover. A byte-identical reference run proves the MODEL on every engine. It does not exercise the engine's own game object at all if that object is not what the reference run plays on - on the reference port, every engine's reference run used the model's aggregate while the game as played ran a Unity MonoBehaviour. A refactor of the engine object therefore needs the engine's OWN game played as its gate, before and after, beside the checksum: a real game driven in Play, every exception attributed. That driver walks one game's own flow, so the package does not ship one: write yours against your game.

What a second game writes

  • Its own Core, all of it. The reference port's interfaces are its own rules (a damage formula, a type chart, and so on); your game declares its own. Nothing here is a framework to inherit from. What transfers is the SHAPE: domain hosts for "a question the model needs answered, or an announcement only the game can render", and nothing else on them.
  • One engine-free aggregate per entity - not a header interface split into facets. Measured on the reference port: one MonoBehaviour implemented 40 facets through 144 explicit pass-through members, one property was declared by seven of them, and exactly one production type implemented all 40, so nothing was segregated where it ships. Give the rules one aggregate per entity, let the engine's object HOLD one and forward its properties, and cut an interface only where a second implementor supplies it differently.
  • The host seam sorted into five kinds before it is ported, because they cost a second engine very different amounts:
kind what it says what it costs an engine
PUNCTUAL "a thing happened" one KEY-ADDRESSED registry per engine, not one implementation per member
ONGOING "a value is now X" one polling loop: the view reads the value each frame
MUTATION the model asking the engine to change state it owns nothing, eventually: it is model state living in the engine object, and it goes away with the aggregate
ANSWER returns a value real work per engine while the value lives outside the model
CONTROL menus, the AI's turn, the camera real work per engine, and honest

Only the last two are irreducible. Measured on the reference port (435 host members, 141 of them ANSWER or CONTROL), most ANSWERs existed only because the entity's state lived in the MonoBehaviour, so the aggregate removes them. - Art addressed by a KEY the model owns and a TABLE each engine owns. The model's own resolver turns an entity into a file name, a test runs it over the disk to write a table (READ or ABSENT per row, never a guess), and each engine resolves the same key to its own imported asset and FAILS LOUDLY, naming the path, when it is missing. Effects already work this way (IEffectPlayer takes a string key). Give your adapters a gate that refuses a placeholder primitive (a cube, a sphere) in a missing asset's place: a plausible frame with the wrong geometry is the failure that hides longest. - Six platform service implementations - every member is one engine call. - The view adapters per engine - the real work, and bounded: the reference port's are 16 methods and 4 properties in all. - Nothing else. No serialisation format, no message bus, no scripting layer. A JSON bridge between the engines loses to event-log replay, because a bridge makes every value cross a wire and a replay makes every value a diff.

The model's gates, G1 to G7

Copy these. Each exists because something passed every other instrument while broken; what transfers is what each checks and the trap that made it. u2ue check --only model runs G1 and the platform-seam gate from the project file.

  • G1 the layer boundary - py layer_gate.py, and its --selftest. No banned namespace in the model's projects, no unaccounted source link out of another engine's tree, and the accounted links kept on a ratchet file that must empty. Its selftest plants a <Compile Include> under the Unity tree and must report FAIL before a PASS means anything.
  • G2 the model's own suite - dotnet test of the model's tests, no engine in the process. Keep in it the tests that assert the cross-engine claim (the Unity build's native run equals the headless reference): they go red after every model change until the Unity side is re-recorded against the new model, as they should. The cure is the plugin sync (G4) and a re-record, never an edit to the test. Beside it, a second suite that plays every authored action headlessly, every expectation READ from the game's data with its provenance or ABSENT with the reason.
  • G3 it compiles on every host - py typecheck.py (the Unity side, headless Roslyn, no editor) and dotnet build of the engine's managed project.
  • G4 the artifact both engines load is the current source - py plugin_sync_gate.py hashes every plugin DLL against what the source builds now; --sync copies them. The order after a sync is: recompile, wait for the domain reload to SETTLE (not compiling, three times running), console_check (the Unity console gate, "The model's tools" below), then the native re-run. A fresh recording timestamp is NOT proof of a fresh assembly: an editor whose compile fails keeps the old one and records against it happily. Run this gate BEFORE any cross-engine diff, never after, because a stale plugin makes every later comparison one of two different games, and nothing in a diff says which side is stale.
  • G5 the slice is byte-identical across engines - cmp, exit 0, on the printed view-call slice and on the event log, and the exit code quoted; not a diff summary, not an md5 quoted in prose. A slice of 31 lines against one of 55 is a DIFFERENT GAME, not a near miss, and the entity ids give it away. An exit 2 (no such file) is the honest row: that side was never produced.
  • G6 the publish proof - before believing ANY artifact an engine produced: sha256sum every DLL in the engine's managed output; read the MVID from the #GUID heap of the CLI metadata of the model DLL there and of the one the current source just built; compare them; and compare each artifact's mtime against the DLL's. A mismatch, or an artifact OLDER than the DLL, means the engine ran a stale model and every artifact since the last publish is not proven. Reading the MVID is about 40 lines of Python, and it is the only thing that tells a fresh byte-identical run from a stale one. The reference port's gate for this names its own DLLs and is not in the package; write yours from this description. Make the run write its own run-manifest.txt naming the assembly it bound (by a type's assembly, not by searching for a name), written on arming so a crashed run still leaves one. The publish recipe, each part a trap met:
  • RunUAT.bat BuildUserSolution -ScriptsForProject=<uproject> -Project=<uproject> -OutputPath=<dir> ONCE PER PATH (Binaries/Managed and Binaries/Managed/net10.0), in Release. Its success line on Unreal 5.7 is AutomationTool exiting with ExitCode=0 (Success); Result: Succeeded is the C++ compile's line, which a publish never prints, so a grep for it finds nothing.
  • The proof run goes through one launcher (the package's scene_tools/ue_headless.ps1, as -game -RenderOffScreen -unattended), with the run's trigger file dropped FIRST; without it the module's startup digest does not run, and a stale logic-Unreal.txt is refused as older than the DLLs.
  • Launch from native PowerShell: UnrealSharp finds dotnet by the literal Program Files\dotnet\ on the PATH.
  • A publish does NOT need the editor closed, because UnrealSharp hot-reloads the DLLs. What must not happen while the owner's editor is open is WRITING the model's sources: a hot reload that lands mid-write fails to compile and can wedge the editor (Chapter 16).
  • Removing a reference does not remove the DLL. A runtime that probes a directory can still bind what the build no longer names; the publish gate fails if an old DLL comes back, and its selftest plants one to prove it.
  • G7 the game actually plays - enter play on the real scene, drive it to a verdict, and capture BOTH a JSON outcome and a PNG; then read the PNG. A gate that reads only the JSON cannot tell a played game from a black screen (Chapter 9 has the measured case). Its second half is easy to skip: console_check with --reset BEFORE the run and again after, and the count of new console errors (consoleNewErrors) is part of the verdict - one new error is RED, not "passed with a note". Three traps in how a result reads on disk: a JSON that exists is not a run, and ok:true is about the HTTP call, not the game (one such file said "ok":true with "turnsTaken":0: it had held a menu and never played); a run that hits a turn cap (TURN_CAP) proves the loop keeps running, not that the rules can end a game; only a real verdict row ("outcome":"DEFEAT", or a win) proves that. And a Unity run driven by a script writes to a scratch folder, never to the folder that holds the reference recording. Give your recorder no default output folder: the reference port's defaulted to the reference directory, so one forgotten option overwrote the recording.

The headless UI capture trap. On Unreal, HighResShot does NOT capture UMG or Slate: a magenta rect painted at FLinearColor(1,0,1,1) over 30720 known pixels read rgb(12,4,1) in a HighResShot frame, identical to a control frame with no widget at all, while the engine's own screenshot showui captured it exactly, 30720 of 30720 pixels at rgb(255,0,255) (the reference port, 2026-09-29). Every HUD capture uses screenshot showui. Finding that before writing a HUD is the point of a probe.

What stays engine-specific, and why

What a port keeps engine-specific, and the rule each item teaches (measured on the reference port, 2026-09-30):

  • Find a moved file's closure with the compiler, in passes. When an engine project stops source-linking game files out of the Unity tree, most links turn out to be needed only by other linked files; the compiler names the rest, and they MOVE into the model byte for byte, keeping their global namespace so no Unity call site needs a using. It takes several builds: a CS0246 on one type stops the binder from naming what the next expression would have needed. The links that remain are deliberate: the measurement pair (float bits, the digest writer) compiled identically into every host, source-linked so there is ONE spelling.
  • Exercise every platform service on real data at start-up, and write what it answered beside the run's artifacts (the reference port's Unreal side writes platform-Unreal.txt), because a host that compiles and answers null for everything cannot be told from a game that ships no data.
  • A behaviour with no equivalent is REFUSED with its reason, not faked. The conformance oracle (conformance_diff --require Unity Unreal) records one failure on the reference port - forward after a 90-degree yaw read (2.220446E-16, 1, 0) where (1, 0, 0) was expected, an axis convention, not rounding - and two skips: Unity's 32 named layers (Unreal uses collision channels and traces) and the screen size (a rendering concern out of parity scope; inventing 1920x1080 would be a fabricated value). A SKIP is an honest gap, recorded apart from a PASS.
  • The float difference is characterised, not waved through (step 7). Every differing row is pinned in logic-allowance.json to its exact bits AND to 1 ULP, so a new row, a moved value or a wider gap is still red; an allowance that let every float difference through would be a fallback, not a gate (logic_diff.py's header records the measurement). The difference is latent in a game's own arithmetic, not caused by the port: any game meets it the moment it runs the same code on two runtimes.
  • Count the seam honestly; do not go looking for a kernel. Your game's seam is the interface set above plus its own domain hosts; a single board interface or a shared kernel package is not the goal. The HUD contract (IHudView, drawn from the board as shown) is the one to copy rather than invent.
  • Expect the Unity side to keep its old shape for a long time. The Unreal side is written once, against the seam; on the reference port the Unity side still nested random sources privately in game files and called JsonUtility directly.
  • A logic gate's captures are greybox, and a capture manifest must be able to fail. Conformance-harness renders (cubes and grey tiles) are right for a logic gate and not to be read as the game. Record an md5 and a byte size per frame on every engine: a manifest that records only a label cannot detect a repeated frame. A capture gate opens the PNG - one effect capture on the reference port caught a loading screen at 0 percent instead of the effect.
  • A test that re-implements the rule it tests passes when the product is wrong. The reference port's Unity-side suite declared simulation types in 48 files, and at least fourteen were static classes holding a SECOND copy of a game rule; a green suite of that shape is not by itself evidence about the model.
  • Decide the logic port's scope, and say it. Logic parity and rendering parity are separate questions; the owner decides whether rendering parity is in the logic port's scope, and nothing above is a rendering complaint.

Traps the model work met

Each was met on the reference port and still bites:

  • Read every engine member from metadata, never from memory. UnrealLogger.Log(logName, message, verbosity) takes the CATEGORY first and the message second; both are strings, so the wrong order compiles perfectly and logs nonsense. Keep a seam map re-verified on every run, with an impossible sentinel row that must report STALE, so the verdicts cannot be assumed.
  • UnrealSharp conventions the compiler is the right oracle for: [UClass] types must be partial (its source generator writes the other half), and AActor.BeginPlay is public virtual, not protected.
  • AStaticMeshActor's root is Static, and a Static component refuses every move in a game world. Set Mobility to Movable and READ IT BACK at spawn, and use the move FUNCTIONS rather than the RelativeLocation UPROPERTY, which never updates ComponentToWorld.
  • AActor.GetAttachedActors returns children REVERSED. Record the order SetParent was asked for and cross-check the count with the engine's.
  • The Unreal editor world never ticks actors outside Simulate or PIE (Play In Editor): -run=pythonscript asserts and -ExecutePythonScript quits before the tick loop runs. A host that must tick has to be IN a world; run it headless as UnrealEditor-Cmd.exe <uproject> <Map> -game -nullrhi -unattended -nosplash.
  • A configured value says so where it is declared. An engine backend that needs a value the engine does not have names where its value came from: a FrameCount kept as its own tick count (Unreal exposes no frame counter to managed code), a FixedDeltaTime set to Unity's 0.02 default (Unreal has no fixed timestep). Naming the provenance is the difference between a configured constant and a fabricated one.
  • A managed reference does not keep an Unreal asset alive. Unreal's garbage collector sees only what the ENGINE holds (UPROPERTYs, the root set, strong pointers); a C# field, a Dictionary cache or a plain C# property on a managed [UClass] is invisible to it. A cache of StaticLoadObject textures handed back a texture the collector was purging (it purges over several frames, and UnrealSharp zeroes the managed wrapper only at the final free, so IsValid does not save you in between): the renderer died with Texture not valid! UE-23902! and then an access violation, six minutes into a long run. Root every asset a cache keeps with UnrealSharp's TStrongObjectPtr<T>, and assert liveness on every cache hit. Make a GC bug deterministic before fixing it: -ExecCmds="gc.TimeBetweenPurgingPendingKillObjects 0.5" (a collection every half second) turned the six-minute crash into one in 32 seconds, every time. Run long runs under that pressure, and fail a run whose log shows the default rate.
  • Move a rule into the model without touching a single call site. When the game's scripts live in the global namespace, C# resolves a global type before one a using imports, so a rule can be added to the model while the Unity copy still exists, the plugin synced, and only THEN the Unity copy deleted: every call site resolves to the model's copy unchanged. Two traps on the way: an alias such as using X = Rule.Nested; cannot see the file's other using lines, so spell its namespace out; and every test project that linked the old file must stop linking it in the same step.
  • A second implementation of an engine type silently wins. A private copy of a shim's Mathf shadowed the bit-verified one (UnityCompat.Core), and thousands of tests ran against the unverified copy with nothing in the build to say so. If you keep a shim, gate it: a second declaration of any type the shim declares fails the build.

The shim route, and why a new port should not take it

A shim declares Unity's value types in namespace UnityEngine (the reference port's UnityCompat.Core, differentially tested against the real UnityEngine at float32 BIT equality) and an engine backend seam (UnityCompat.Engine: an IEngineBackend seam, a static facade, a LifecycleScheduler, a FakeBackend). A project's existing call sites then compile untouched; in a Unity build the real UnityEngine wins and the shim is not referenced. It is not part of this toolkit's package.

It is a good first move for an EXISTING codebase: it is how the reference port's Unreal side ran a game byte-identically before any adapter existed, and it stays useful as the PARITY ORACLE during a migration (the reference port's backend tests are 38 scenarios every backend must pass). But it keeps a game Unity-shaped for as long as it is load-bearing. A game starting its port today writes its Core engine-free from the beginning and never grows a shim. Reach for one only to get an existing Unity codebase moving before the extraction is done, and treat every day it survives after that as debt.

The shim's tooling is not in the package either. If you build a shim anyway, it needs four instruments, each measured on the reference port's: a gap compiler (compile the scripts against the shim and rank what is missing; the ranked list is the worklist), a surface census of the Unity API by call site, an oracle of which UnityEngine members are callable headlessly, and a differential test of the value types against the real UnityEngine, bit for bit. The census is also why the seam should be small: on the reference port Vector2 alone was 15.9 percent of call sites, the top 5 symbols 48.3 percent and the top 30 83.4 percent. The package's nearest instrument is py -m u2ue --project <game> inventory, which lists every Unity API family each type uses (by family, not by call site).

The model's tools

These are the tools the package ships around the model. They sit at the toolkit root unless the part says otherwise; "check" says whether u2ue check --only selftests runs the tool's own selftest.

tool part what it does check
layer_gate.py root the model layer knows no engine (G1); u2ue check --only model runs it from the project file yes
host_gate.py root the platform-seam gate: a platform member declared only in the hosting folder yes
typecheck.py root does the game's C# compile - no Unity, no window, no focus stolen (G3) -
plugin_sync_gate.py root the model's plugin DLLs that Unity loads are built from the current source (G4) not run: its selftest corrupts and restores the plugin DLL an open editor loads
logic_diff.py root the game's logic digest compared across engines - what u2ue parity runs yes
console_check.py root the Unity console gate: did the thing just done put NEW errors in the log yes
u1e_publish.ps1 effects_tools the managed project rebuilt and published to BOTH managed paths, then a run started headless -
publish_verify.ps1 scene_tools proves a managed publish actually RUNS, not just that it built -

The reference port also ran gates written for its own model - a gate that refuses a stand-in drawn where the game's own asset belongs, one that proves the game's own effect calls still happen once and in order, a finder for code that compiles on Unreal but never runs, a census of its host interfaces. They are not in the package: each is the shape of a gate your game's model may need, written against your own model's names.

Your game supplies its own model projects and banned-namespace list (layer_gate.py), its host member names (host_gate.py), its plugin folder, its reference run, and the slice files the engines diff byte for byte.

Game integration: the effect ledger

The Unreal adapter reads an effect ledger: one row per effect key, naming its built system, joined from the three stages' own outputs (the key's verdict, its IR timing with provenance, what was built) and CHECKED against the disk, so the ledger and the assets cannot disagree. The reference run, played headless on Unreal, proves the game fires what was built.

tool part what it does
u1e_ledger.py effects_tools writes the effect ledger the Unreal adapter reads, checked against the disk
u1e_battle.ps1 effects_tools runs the game's reference run headless on the ALREADY-PUBLISHED DLLs and says which frame is which moment, so a frame is always opened knowing what it should show; for asset-only changes
u1e_run.ps1 effects_tools builds the reference run's effect systems, headless

Your game supplies its adapter's effect hook (the model asks IEffectPlayer for a key; the ledger turns the key into a system) and its reference run.

6. Transforms, scenes, UI, audio

Who this is for: the porting developer - after this chapter you can convert any transform between the engines, find the nodes Unreal cannot place, import a level and a UI screen and hold each to Unity, and bring the game's sound across. The first half is the method; from "What the UI capture measured" on, the chapter is the measured lessons and the tools behind each step.

The conventions, in one place

u2ue/transform.py holds every transform convention the port uses. Use it rather than writing your own: its selftest holds it to the effect converter's own functions (200 random cases), so the two cannot drift apart.

Unity Unreal
units metres centimetres
axes x right, y up, z forward x forward, y right, z up
handedness left left
position (x, y, z) (-x, z, y) x 100 - transform.position
direction (x, y, z) (-x, z, y) - transform.direction
rotation quaternion (qx, qy, qz, qw) (-qx, qz, qy, qw) - transform.rotation
scale (sx, sy, sz) (sx, sz, sy) - transform.scale
Euler angles Quaternion.Euler(x, y, z) turns Z, then X, then Y, about the fixed axes (MEASURED, Unity 6000.3) -

From Python:

>>> from u2ue import transform as T
>>> T.position((1.0, 2.0, 3.0))                      # Unity metres -> Unreal centimetres
(-100.0, 300.0, 200.0)
>>> T.rotation((0.0, 0.7071068, 0.0, 0.7071068))     # Unity's 90 degrees about y (up) -> Unreal's 90 degrees about z (up)
(-0.0, 0.0, 0.7071068, 0.7071068)

How each engine composes a hierarchy

  • Unity composes a Transform chain as matrices: each level's rotation times scale applies to everything below it. A rotated child under a non-uniformly scaled parent is therefore sheared.
  • Unreal stores a component's world transform as rotation, scale and translation. Its rule for composing a child with its parent is READ from the engine (Engine/Source/Runtime/Core/Private/Math/TransformVectorized.cpp:295-323): with no negative scale on either side, rotations multiply, scales multiply componentwise, and the child's offset is turned and scaled by the parent; with a negative scale, it multiplies the full matrices, normalises the axes and re-applies the signs (TransformVectorized.h:1552-1587). Neither branch can hold a shear.

transform.compose_matrix and transform.compose_trs reproduce both; transform.shear_of and the corner errors measure the gap.

Finding the nodes Unreal cannot place: u2ue shear

py -m u2ue --project <game> shear --gltf <scene export>.gltf --json shear.json
py -m u2ue --project <game> shear --from Assets/<Scene>.unity

The verb reads a scene either as the glTF file the scene pipeline exports (below) or straight from the Unity scene file, with no export. It composes every node both ways and lists each sheared node: its axes' worst non-orthogonality, how far the corners (+-1, +-1, +-1) land apart (unitCornerCm), whether it draws, and, for a drawn glTF mesh, its bounds' corner error. Measured on the reference port's first battle map: 46 sheared nodes, 2 of them drawing (a rope bridge's meshes, 63.46 and 55.89 cm off at their box corners). A sheared node that draws nothing still moves its children. Whether such an error is accepted, baked into the mesh, or fixed in the Unity scene is the owner's decision, made with the number. Then pin it with a gate, so a later change that makes it worse fails: the scene's fidelity gate (below) holds the world bounds' residual to the scene's own baseline.

Scenes: u2ue scene

Scope: one Unity scene, imported into Unreal as a new level. Precondition: the project file names the scene and its work folder, and the scene's own fidelity baseline exists. Minimal guarantee: a scene with no baseline is refused, never graded against another scene's numbers, and a sheared node's error is a number the owner decides on. Success guarantee: the imported level passes the scene's fidelity gate, every leg at or better than its baseline. Trigger: one of the game's scenes is to run in Unreal.

py -m u2ue --project <game> scene --dry          # the scene's paths, opened; the host's state
py -m u2ue --project <game> scene export         # REFUSED here: runs in the owner's editor, in a window - prints the trigger
py -m u2ue --project <game> scene import         # the glTF into a NEW level through Interchange (Unreal, headless)
py -m u2ue --project <game> scene readback       # the saved level read back (Unreal, headless)
py -m u2ue --project <game> scene check          # the fidelity gate against the scene's own baseline (no editor)

The project file names the scene: "scene": {"unity": "Assets/<Scene>.unity", "name": "<Name>", "dir": "<scene work folder>", "content": "/Game/.../<Name>"}. Until it does, port reports the scene stage ABSENT (Chapter 4). The gate grades the level against that scene's own measured baseline, <scene dir>/fidelity-baseline.json (scene.dir, the work folder above): the counts and residuals every leg holds, and the materials and actors the scene expects by name. It exits 0 when every leg holds, 1 when one moved, 2 when an input or the baseline is missing. The reference port's first battle map, graded against an earlier readback of its level:

py -m u2ue --project <game> scene check
SCENE FIDELITY GATE - <Name>, Unity scene against the imported Unreal level
...
  PASS world AABB residual has not regressed     1037 row(s) (baseline 1037) worst centre 1.431278 / extents 1.453828
CHECKS 45, FAIL 0
VERDICT PASS

Re-read after the level's lighting was changed on purpose, the same gate reads 3 FAIL (the sun, the sky light and one colour): it grades Unity's numbers, so a deliberate departure stays red until the owner accepts it by name.

The verbs wrap the generic legs of the pipeline below. A real level also needs steps between import and readback (textures, material parents, lighting, outline hulls, effect actors). Those are not verbs yet; their tools are under "The scene tools" below. The gate grades the finished level.

  1. Export from Unity with glTFast (an Editor script in the game's project): meshes, materials and textures one to one; inactive subtrees skipped and listed; every value not carried named ABSENT; the terrain baked from its TerrainData, the asset where Unity keeps a terrain's shape and painted layers (heights, the splat layers' albedo: the colour of each painted layer).
  2. Import into Unreal with Interchange, the engine's own import pipeline (an editor Python script in the host).
  3. Check with scene_fidelity_gate.py: hierarchy, materials (slot by slot against the .mat), textures, lighting and placement against Unity's own files, through a headless readback of the saved level.

A trap: a scene imported through glTF arrives in a frame the pipeline chose (glTFast negates x; Unreal's importer takes glTF's y-up as z-up), so a level and a hand-placed actor need not share a frame. Measure the imported level's frame once (one small class is enough) and convert every hand-placed actor through it.

Prefab YAML: what a reader must handle

The effect reader (u1e_ir.py with u1e_nested.py) handles nested prefab instances with their modifications (a nested object's id is the instance's id XOR the source object's), prefab variants, legacy prefab records, m_RemovedComponents, m_RemovedGameObjects (the removed object leaves the instance with its child subtree and their components), and nested MODEL instances (left out and named). m_AddedGameObjects and m_AddedComponents are not ported yet: a prefab that uses either is refused by name. Unity's YAML writes booleans as 0 and 1, so the loader keeps the words On, Off, Yes, No as strings.

UI

Unity's uGUI (Canvas, RectTransforms, layout groups, TextMeshPro) has no one-to-one Unreal counterpart: UMG and Slate lay out differently. So the toolkit does not rebuild a screen as a UMG tree. It captures the Unity Canvas as Unity resolved it in Play mode, lays it out in Unreal with a port of uGUI's own solver, and paints it in one widget's paint pass (UUserWidget.OnPaint), because UnrealSharp's UWidgetTree.RootWidget is read-only and a UMG tree cannot be assembled from C#. Each captured state is held to Unity's own pixels.

The generic part ships as the library U2ue.Ui (u2ue/runtime/U2ue.Ui): uGUI's layout, meshes, raycast and selectables, and TextMeshPro's layout, with no game reference. Its own tests hold it to Unity's captures, and a planted transform defect fails 264 of them:

py -m u2ue --project <game> ui test
Passed!  - Failed:     0, Passed:   398, Skipped:     9, Total:   407, Duration: 3 m 28 s - U2ue.Ui.Tests.dll (net10.0)

Not in the package yet: the capture. Today it is the reference port's Editor script; shipping it as the package's Editor assembly is on the roadmap (Appendix B), and until then a second game supplies its own editor's capture route ("The UI tools", below). The bindings, which view model feeds which panel, stay the game's. port lists the UI as an EDITOR stage: it needs a free Unity editor, so port never opens one (Chapter 4).

Scope: one game's uGUI screens, laid out in Unreal by a port of uGUI's own solver. Precondition: each screen can be reached in Play mode in the game's own editor. Minimal guarantee: a font whose glyph indices differ is refused, and a panel with no view model and binding is not drawn. Success guarantee: each captured screen is laid out in Unreal as Unity resolved it. Trigger: a screen of the game is to run in Unreal.

The UI port, in order:

  1. Capture the Canvas in the game's own Unity Editor in Play mode: every RectTransform, its anchors and its components, as Unity resolved them.
  2. Hold the library to Unity: py -m u2ue --project <game> ui test runs U2ue.Ui's tests against Unity's captures.
  3. Convert each capture into a folder Unreal reads: py -m u2ue --project <game> ui convert <capture dir> --screen NAME [--out DIR] (--out defaults under the project's work.ui). It finds each TextMeshPro font's TTF by the GUID its font asset recorded, and refuses a font whose glyph indices differ.
  4. Bind each panel to its view model in the game's own host; only a panel with a view model and a binding is drawn.
  5. Paint the bound panels in one UUserWidget.OnPaint, laid out by the solver from the converted folder.

Audio

Authored clips (.wav, .ogg) import into Unreal as Sound Waves directly. Which sound plays, and how loud, should be a rule in the model (one presentation class is enough), so both engines pick the same sound. Clips Unity generates at run time are rendered once to float PCM and played through a small C++ bridge that hands the samples to Unreal's mixer unconverted, as a 2D one-shot (played once, with no position in the level, like Unity's 2D voices). The bridge ships as the host template's U2ueAudio plugin (Chapter 13). It builds in a host and plays headless: the self test's tone, captured from a headless run on 2026-10-15, passes its judge. A Unity AudioSource still maps by hand (Appendix B). Headless runs pass -DeterministicAudio so nothing reaches a device (Chapter 16).

Animation and physics

Not covered (Chapter 5): no tool is claimed for Animator controllers, Mecanim retargeting or physics simulation. What a port of either needs, and what to measure in Unity first, is in Appendix B. The effects path ports one animation case: an Animator on an effect's root that drives its scale (Chapter 7).

What the UI capture measured

The capture (the reference port's Editor script, served on its editor bridge as /ui/capture) records the live uGUI subtree in Play: the RectTransforms AND their resolved rects, the layout components and LayoutUtility's answers (each element's minimum, preferred and flexible size, as uGUI's layout reads them), sprites with their pixels, mesh effects, selectables, and TextMeshPro's own per-glyph layout. Rebuilding from what Unity resolved, rather than from the authored values, surfaced these rules, each measured on the reference port:

  • The look is not in Image.color. uGUI's Outline draws FOUR offset copies behind the graphic, with alpha = the effect's alpha x the vertex alpha / 255, in bytes; under a translucent fill they tint the whole interior. A panel authored navy was teal on screen because of it.
  • Unity (linear colour space) blends in LINEAR space; Slate blends in GAMMA space. The same layers came out (55,147,165) in Unity and (41,99,117) on Slate. The fix is exact where the UI covers itself: composite the layers under each translucent graphic in linear, then solve its colour for the gamma blender (U2ue.Ui's UiMesh.SolveForGammaBlending). Glyph edges keep a residual (text about 0.85 of the ink).
  • Unity evaluates TextMeshPro's float maths in double, rounding only on a store: in float32, TextMeshPro's preferred-size rounding lands 0.01 off (14.41 where Unity gives 14.40). The port matches at float32 bit equality once it does the same (TmpF32 in U2ue.Ui).
  • uGUI's layout is a rebuild of ROOTS in depth order, four passes each (horizontal sizes bottom-up, horizontal control top-down, then the same vertically). An Image's preferred size is its sprite's MIN size when sliced, not its rect: a real Unity behaviour the rebuild must reproduce.
  • HighResShot never captures UMG or Slate; screenshot showui does. A UI frame taken with the former shows the level and no UI while the log says the widget painted (Chapter 5 has the measurement).
  • Slate pixel-snaps DrawBox and DrawText vertices (there is no NoPixelSnapping through UMG's paint helpers) and puts a text baseline at the draw position + round(face height x ppem / upem) + round(descender x ppem / upem), where ppem is the font size in pixels per em and upem the font's design units per em. Place glyphs ONE BY ONE at Unity's origins: a string drawn by Slate drifts (1.7 px over 12 characters), because its hinted advances are not TextMeshPro's.
  • Putting the owner's editor into Play steals focus, so a capture runs only while the editor is free (Chapter 8's window rules).

The effect readers: the IR extraction tools

What extract runs (Chapter 7 has the pipeline): every effect the game can fire, resolved from the game's own data to a prefab, then each prefab's ParticleSystems READ into the engine-neutral IR, with nested prefabs expanded, the game's rules that switch emitters off applied, and missing assets named. The column "check" says whether u2ue check --only selftests runs the tool's own selftest (Chapter 21 lists them all).

tool part what it does check
u1e_resolve.py effects_tools the reference port's own key source: every effect key its reference run fires, resolved to a prefab the way the game's code resolves it. A second game uses particle_prefabs or its own adapter (Chapter 18) -
u1e_ir.py effects_tools the engine-neutral IR for every resolved prefab; no Unity runs -
shuriken_ir.py vfxport Unity Shuriken (ParticleSystem) to the IR: the per-emitter reader u1e_ir.py calls -
gen_ir.py vfxport IR for a deliberately mixed sample (the most-used prefab of each pack, a simple one and a heavy one), so a first pilot shows the range rather than a best case -
u1e_nested.py effects_tools a prefab's nested prefab instances expanded, so the IR reads every particle system it holds yes
u1e_gamerules.py effects_tools what the game draws of an effect, as the IR read it, turned into the emitters the build makes yes
u1e_missing_assets.py effects_tools which material and shader references of the IRs point at an asset that does not exist in the project yes
u1e_keep.py effects_tools a rebuilt effect's previous asset is kept until the new one is saved -
u1e_names.py effects_tools one mapping from a built system's emitter name back to its IR emitter, for every read-back check -
u1e_names_gate.py effects_tools did every emitter of every built system keep the name the converter gave it yes
niagara_names.py vfxport the name every emitter of a converted system carries in Niagara, worked out before it is added yes
fx17_asset_names.py effects_tools Unreal asset names that two different Unity files would share -
u1e_rootanim.py effects_tools every effect key whose prefab root carries an Animator that scales it, read off its clips -
u1e_peak_fast.py effects_tools the IR reader's peak-time arithmetic, vectorized, so a whole game's prefabs do not take hours -

A second game supplies where its effects are named (or the default: every prefab holding a ParticleSystem) and its Assets root.

The scene tools

The level steps that u2ue scene (above) does not wrap yet: the scene's own particle systems, its ambient light and exposure, and its material parents. Each is a script with its own log, written for the reference port's first battle level.

tool part what it does
p29_read_systems.py scene_tools every Unity ParticleSystem in the scene read, headless
p29_build.py scene_tools one Niagara system built per Unity ParticleSystem, headless
p29_place.py scene_tools one Niagara actor per Unity ParticleSystem, placed at its exact world transform
r2b_probe.py scene_tools the ambient-light probe that must run before anything is changed
r2b_ambient_sh.py scene_tools what exactly Unity's bakedGI term (the ambient light a surface receives) gives a surface
r2b_exposure.py scene_tools the level's exposure white point set to a value, and saved
s49_measure.py scene_tools the ported particles measured, not eyeballed
p27b_probe_inputs.py scene_tools the input names of the material nodes a step adds, measured first: Unreal's connect_material_expressions returns False and silently leaves the input empty when a name is wrong
p27b_apply.py scene_tools the level's material parents authored on Unreal's own shading models, and every instance rebuilt from the plan, headless

None has a selftest run by u2ue check. A second game supplies its levels, its own board-to-tile mapping if it has one, and its lighting reference.

The UI tools

The tools behind the UI port above. The UI part has its own README in its folder. A HUD is drawn by the model's IHudView from the board as shown (Chapter 5); its gate is written against your own HUD, so the package has none.

tool part what it does
ui_capture_unity.py ui one live Unity screen captured: Play, wait until the screen has SETTLED, pause on one frame, capture
ui_capture_battle_states.py ui every state a panel shows in, captured in ONE Play session
ui_convert.py ui one capture into one screen folder the Unreal side reads (what u2ue ui convert runs)
ui_compare.py ui a captured Unity frame against the Unreal rebuild of the same screen, node by node
ui_oracle.ps1 ui one captured frame redrawn on Unreal from Unity's OWN draw data, the 8-bit result kept
ui_oracle_all.ps1 ui every captured state's UI-only frames redrawn that way and held to Unity's
ui_oracle_compare.py ui an oracle frame held to Unity's frame of the same capture, pixel for pixel
ui_preview.ps1 ui one converted screen drawn on Unreal ON ITS OWN, one frame of it, and what the run said
ui_clicks.ps1 ui a screen driven through the LIVE mouse path headlessly, with a scripted pointer
ui_color_probe.py ui Unity's native UI vertex-colour path, measured from pixels
audio_check.py ui is what Unreal PLAYED what the run says it played

The oracle is the instrument to copy: redrawing Unity's own draw data on Unreal separates "the layout is wrong" from "the renderer draws the same mesh differently". A second game supplies its screens (the capture list), its editor's capture route, and its fonts' TextMeshPro assets.

Meshes, textures and sprite art: the tools

Binary FBX and Unity text-asset meshes are read without an editor, EXR frames (images stored as half floats) turned into Unity's reference PNGs, and saved Unreal assets read without Unreal.

tool part what it does check
u1e_fbx.py effects_tools the few facts the build needs out of a BINARY FBX, read off the file with no SDK -
u1e_objmesh.py effects_tools a Wavefront .obj mesh read into the shape the FBX writer takes yes
u1e_unitymesh.py effects_tools a Unity Mesh saved as a TEXT .asset (YAML, the vertex and index buffers as hex) read into the same shape yes
u1e_exr.py effects_tools a frame exported as EXR turned into the 8-bit sRGB PNG Unity's reference camera writes; standard library only yes
uasset.py scene_tools a saved Unreal 5.7 editor .uasset read without an editor and without Unreal's Python -

The sprite and tile art steps are written per game, so the package does not ship them. Follow this method, in this order; each step is a lesson from the reference port:

  1. Create everything a sprite unit needs headlessly: its texture, its card mesh (the flat plane the sprite is drawn on) and its material, in one headless run.
  2. Read which properties the engine build exposes before you set one. A texture (UTexture2D) property named in the documentation did not exist in Unreal 5.7.1. List the properties; never guess a second name.
  3. Give every imported texture the settings Unity's own importer recorded for it (its .meta), and prove each one took.
  4. Render one card on its own, away from the level's lighting, with its material and texture measured. "Invisible in the level" then becomes one cause instead of three guesses.
  5. Export an imported texture back out and compare it with the PNG it came from.
  6. Make a card two-sided only from the rule that says so, and keep the source of that rule beside it.
  7. Rebuild the material the game draws with, which may not be the one the prefab serializes. On the reference port the game built its card material at run time. Read the code that builds a material, not only the asset.
  8. Read a debug material's blend mode, shading model and outputs before a mesh wears it.
  9. Give a sprite card Unity's depth of field the way Unity's card takes it, through its own depth pass.
  10. Import the textures the game loads at run time (highlights, overlays) headlessly too: nothing in a scene names them.

7. Effects

Who this is for: the porting developer - after this chapter you can run the effects pipeline that turns the game's Shuriken particle effects into Niagara systems, tell a real gap from an emitter Unity does not draw either, and close a gap with the route protocol.

Shuriken particle effects are converted end to end. This chapter is the shape of the route; Chapter 11 gives the reasons behind each step, and the traps.

The pipeline

flowchart TB
  U["Unity project: prefabs, materials, .meta"] -->|extract| IR[("IR: one JSON per effect")]
  IR -->|check| G{"selftests + field gates"}
  G -->|build| N["Niagara systems + build record"]
  N -->|read| R[("particles per frame")]
  N -->|photo| P["Unreal frames beside Unity's"]
  R -->|judge| J{"read-back checks, each with a plant"}
  J --> REP["acceptance page"]
  P -->|LOOK| REP
  REP --> M["metrics + tempo"]
step runs in tool what proves it
extract no editor u1e_ir.py over shuriken_ir.py every key an IR file or a named refusal; every path it names exists
check no editor u2ue check every tool's own selftest; every IR field read or excused with its values
build Unreal, headless u1e_build.py running build_niagara.py the build record: per key its verdict, every module written, every absent emitter with its reason
read Unreal, headless u1e_color_size_readback.py read-back checks per 1/60 s frame, each refusing its plant
photo Unreal, headless u1e_fx_photo.py, u1e_photo_sheet.py the pair sheets (each effect's Unity frames above its Unreal frames), LOOKED at; capture artefacts (frames the capture itself spoiled) labelled, never counted
report no editor report_build.py every number from a record, with its denominator and its age

py -m u2ue --project <game> port --run runs these steps in order (its check stage is check --only gates). build, read and photo launch a headless Unreal, so port runs them only with --with-unreal, one Unreal at a time (Chapter 4).

The IR

One JSON file per effect key, read off the Unity YAML. Every value carries how it was read (readAs: the fields it came from and the mode Unity serialized it in, its minMaxState), so a reader of the IR can tell a constant from a curve from a range, and a value that was not read from one that was zero. An excerpt (a snow emitter, from the second game):

{
 "key": "unity.prefab.4ca04dc9501451e498e3f029e625ccaf",
 "lifetimeSeconds": null,
 "naturalLengthWhy": "LOOPING emitter(s) Snow_Particles: no natural end",
 "emitters": [{
   "name": "Snow_Particles", "duration": 5, "looping": true, "simulationSpace": "World", "maxParticles": 900,
   "startLifetime": {"mode": "constant", "scalar": 2.2, "value": 2.2, "readAs": "scalar (minMaxState 0)"},
   "startSize": {"mode": "randomConstants", "scalar": 0.3, "min": 0.15, "max": 0.3,
                 "readAs": "minScalar..scalar (minMaxState 3, serializedVersion 2)"},
   "emission": {"enabled": true, "rateOverTime": {"mode": "constant", "scalar": 500, "value": 500, "readAs": "scalar (minMaxState 0)"},
                "bursts": []},
   "shape": {"enabled": true, "type": "Box", "scale": {"x": 30, "y": 1, "z": 30}, "...": "28 fields in all"}
 }]
}

lifetimeSeconds is null, not a number: a looping emitter has no natural end, and what ends a spawn of it is the game's code, so the IR says so instead of inventing a length.

The converter

vfxport/build_niagara.py writes Niagara stacks (each of an emitter's scripts is a stack of modules, run top to bottom) through Unreal's FXConverterUtilitiesLibrary. build_emitter is a loop over twenty stages in the order Unity's own modules run: setup, emitter state, spawning, particle spawn, shape, start speed, update, colour / size / rotation over lifetime, gravity, force, noise, velocity over lifetime, collision, renderer, flipbook (texture sheet animation), sub-emitter roles and trails, inherit velocity, and the modules not ported (named per emitter). A rule measured in Unity is re-derived from its bake at build time by its judge (Chapter 8): a rule that stops holding stops the build instead of drawing wrongly.

What a gap is, and what it is not

An absent emitter is a GAP only when Unity draws it. The report counts apart, each by a measured or read rule, what Unity does not draw either: a sub-emitter (a child system that a parent's particles start at their birth, death or collision) Unity never fires, one the game never starts, one whose renderer draws nothing, one Unity measured at zero particles. Measured on the reference port: 348 emitters that its first acceptance pages counted as gaps were of these kinds.

The reverse is a gap too: an emitter the port DRAWS where Unity never does. Coverage counts it as drawn, so nothing flags it unless a probe looks. The reference port had one: a "spawner" particle living a ten-thousandth of a second, whose three Birth children (sub-emitters started as each particle is born) Unity never fired while the port drew them for a few frames. When a probe measures zero particles at every moment a parent could fire a child, that fact goes in a list derived from the probe record (never typed), the converter refuses the child by name, and the report counts it absent, as in Unity. That is data for one effect, not a rule taken from one case.

The worst gap is a silent one

Most Shuriken fields are min-max values: a constant, a curve, a random value between two constants, or one between two curves (Chapter 11, "Two models of one effect"). A reader that reduces a value it cannot port (a curve to its first key, two curves to one) and writes no note makes a gap the report cannot see: the emitter counts as drawn. The reference port found this class twice, the second time by auditing for it after the first:

  • an emission rate authored as a curve was built as its first key: a constant rate, or no spawn at all where the curve starts at 0 (52 emitters, not one named);
  • start size, start speed, start lifetime and gravity authored as curves read the same way (46 emitters).

The rule: every reader of a min-max value either ports its mode or writes a SUBSTITUTED note, which the report counts as a stand-in. When one silent reader is found, audit every reader of the same kind of value before calling it fixed.

What the measurements say: a rate curve is the scalar times the curve at the LOOP's normalized time (the time into the loop over the duration), the k-th particle born where its integral reaches k. A start size or lifetime (one curve or two) reads the curve at the END OF THE STEP that emitted the particle; a start speed reads it at the particle's own emission time inside that step. Gravity reads its curve at the emitter's normalized time on every step, and with two curves each particle keeps one fixed fraction between them. All of them run on the EMITTER's clock, which starts after its start delay and wraps when the system loops. Which Niagara parameter gives each of those instants is in Chapter 11 ("Two clocks"): read the engine before you trust a parameter's name.

When a rule fits most of the data but not all of it, record the variable you are missing before modelling around the gap. The first probe of these rules recorded only each particle's age, and a size read one step late looked like a rule that held for 4 particles in 19. The second probe recorded the step each particle first appeared on, and the same data then fitted one rule exactly.

A companion emitter needs its parent's lifecycle rule. A trail is drawn in Niagara as a ribbon (a strip through a list of points), which runs as its own emitter on its own loop. A sub-emitter child's emitter already lived until its parents' last trigger, but its trail's loop was timed from the system's start: the trail closed while the fired particles were still alive, and sooner still in an emitter whose time was rescaled. When an emitter gains a lifecycle rule, every emitter that exists only to follow it needs the same rule.

Porting a gap: the route protocol

  1. Find the root: the report lists absent emitters by root (the emitter a gap is charged to: see gap root), and what porting each root would bring back.
  2. Read or measure the Unity behaviour (Chapter 8): a judge first, its plant, then the bake.
  3. Write the route behind a VFXPORT_<NAME> switch, default off.
  4. Prove it offline with vfxport/whole_trace.py (Chapter 9, "Proving a route offline"): off, identical engine calls on every emitter; on, exactly the emitters --expect-only names change.
  5. Trial: build the affected keys with the switch on, in a content root of its own (an Unreal content folder apart from the project's content_root) so the trial cannot touch the accepted build; then read, judge (with the plant), photograph, LOOK.
  6. Flip with its evidence row in patch_flip_defaults.py.

A change to a tool a running build loads is written as a patch script with its proof (--prove on a copy) and applied (--land) after the build: a build that changes behaviour half way through is two builds, and neither is the one that was proven.

Materials

Unity effect materials use custom shaders. The blend mode is a NUMBER in the material (_DstBlend == 1 means additive), never the shader's name; each distinct shader family needs one hand-authored Unreal parent material, after which every material of that family is an instance with its values read off the .mat (a material variant's values come through its parent, m_Parent). Built-in shaders and materials are named off the Editor's unity_builtin_extra (set unity.editor). A family with no parent yet is refused by name.

Lit materials

A lit (URP Lit or Shader Graph) material cannot use Unreal's lighting and look the same: the BRDF, the ambient and the reflection decode differ. The toolkit evaluates URP's own lighting inside the Unreal material:

  1. The surface comes from the HLSL Unity generated for the Shader Graph (the translator u1e_sgport.py): texture samples with their tiling, keywords as scalars, Unity's frame for positions and normals. A graph that moves vertices in object space, or that includes custom HLSL, is refused by name.
  2. The lighting is URP 17's Lit, transcribed from its source (u1e_urplit.py): the metallic and specular workflows, the main light, per-pixel spherical-harmonics ambient, the reflection probe's mip and decode, emission added raw.
  3. The inputs are measured, not assumed: one window reads the scene's sun (colour, intensity, direction), its 27 ambient coefficients and its default reflection cube (every face of every mip), which are baked into the parent material.

The route is VFXPORT_URPLIT, on by default since its trial's photos were looked at against Unity's frames taken under the same lighting (the photo probe's lit option opens the scene and copies its sun). The binormal sign of Unreal's tangent frame is kept as Unreal's and named until one mesh at a fixed transform, lit in both engines, decides it. Named, not drawn: fog, shadows, screen-space ambient occlusion, and lighting that changes at run time.

Lights on effects

Point lights an effect prefab carries are read with the rule that turns each on (on at every play; on when a pooled instance is reused; never) and spawned on the played effect as Unreal point lights, attached so they follow it. The mapping, READ from both engines' source (d is the distance to the light, r its range, and saturate clamps to 0..1, so the saturate term is a window that fades the light to zero at its range):

Unity (URP) Unreal
1 / d^2 x saturate(1 - (d^2 / r^2)^2)^2 inverse-squared falloff, AttenuationRadius = 100 x r (the same range window)
intensity I, diffuse with no 1 / pi pi x I candelas (Unreal's Lambert divides by pi)
color.linear x I the colour's sRGB bytes, through the engine's own sRGB round trip
shadows CastShadows = false, the light made movable. The reference game turns its effect lights' shadows off at spawn, so the mapping never casts shadows: a game that keeps them on gets lights without them

The Unity side was measured on lit pixels: a probe renders each light on a lit plane, light on and off, and a judge holds the difference to URP's formula; on the clean bake all ten cases fit at a ratio of 1.0000 (Chapter 8). The named residuals: URP's diffuse carries a 0.96 that Unreal's does not, and Unreal's distance term is 1 / (d^2 + 1 cm^2).

Beyond particles

Effect prefabs carry more than ParticleSystems. The toolkit inventories them and treats each as its own class:

what today
an Animator on the effect's root driving its scale ported
point lights ported (above)
a Timeline (PlayableDirector) starting groups at their clip times the law measured (Chapter 8); the route written and proven offline behind VFXPORT_TIMELINE, default OFF; its trial is NOT YET
TrailRenderers the law measured and reproduced exactly by U2ue.Runtime.TrailLaw (72 of 72 frames, 15 of 15 meshes); the Unreal draw is NOT YET
audio sources listed

Appendix B has the plan for each NOT YET.

8. Measuring Unity

Who this is for: the porting developer - after this chapter you can measure a Unity behaviour the port must reproduce exactly: write its judge first, run its probe in the game's own editor without costing the owner anything, and make the build rely on the measurement.

Unity's documentation does not state most of the rules a port has to reproduce exactly: the frame a sub-emitter's particle is born in, how a TrailRenderer drops its points, what a Timeline does to a ParticleSystem before its clip starts. A port that guesses at them looks right in a screenshot and wrong in the game. So when no file states a rule the port relies on, the rule is MEASURED in Unity itself and kept with the run that measured it. Chapter 9 gives the rule behind this: every value is READ, MEASURED or named ABSENT, never a plausible number.

A rule is measured with a probe, a judge, a bake, and a window in the game's own editor.

The parts

part what it is where
probe an Editor C# script that sets up a case in Unity, steps it, and writes every value it observed to a JSON fact file. It is triggered by a file, so nothing has to click vfxport/unity_probe/*.cs
judge a Python script that states the rule a port will rely on, and READS it off a fact file or REFUSES it with the numbers. Written and selftested before the bake vfxport/unity_probe/*_judge.py, *_check.py
fact file the bake: what Unity did, with the Unity version it ran on shared/conformance/*.json
window a short, guarded session in the game's own editor that puts a probe in, runs it, and takes it out again u2ue window (u2ue/verbs/window.py); a window is a JSON spec

Write the judge first

A judge names the rule in terms a port can use ("a point is dropped once its age on Time.time passes time", where Time.time is Unity's game clock and time the TrailRenderer's own Time setting), and the evidence it needs to READ it ("every removed point was still present at its last age at or below time plus one frame, and gone at its first age above time less one frame, with at least 10 removals seen"). Its --selftest builds synthetic facts that obey the rule, and planted defects that each break it one way; the judge must accept the first and refuse every plant. Only then is the probe run.

The order matters. A judge written after the bake is fitted to the bake, and passes whatever Unity happened to do. A judge written first can be wrong: then the bake refuses it, the numbers say why, and the rule is restated and re-planted. Where you do not know the answer, the judge must not assume one: the TrailRenderer judge's HOLD case reads FROZEN, DRAINED or CHANGED off the facts, and the bake answered FROZEN (a still trail neither adds nor drops a point; points expire only while it moves).

py vfxport/unity_probe/trailrend3_judge.py --selftest      # the plants bite
py vfxport/unity_probe/trailrend3_judge.py                 # the bake: exit 0 READ, 1 refused, 2 no input

When the judge refuses the bake

A refusal is information, never a reason to loosen the judge. The point-light bake is the worked example. Its probe renders each case with the light ON and with it OFF, and the judge holds the difference to URP's formula (Chapter 7, "Lights on effects"). Its first judgement refused cases for two causes, each found in the facts before anything changed.

  • white_diffuse was wrong by a ratio that grew toward blue. Its OFF render, the first after setup, was all zero where every later OFF render held the scene's ambient, so the ambient was read as light. The probe now throws two renders away first, and the judge refuses, by name, a case whose OFF render disagrees with its surface's other OFF renders.
  • Every other failing sample sat on row 272, where the game camera's full-screen pass (which samples the frame in blocks of pixels) computes floor(272.5 / 720 x 330.275) = floor(125.0003): on an exact block edge the GPU's float can land either side. The judge now accepts either block on an edge, and counts how many samples it did that for.

Re-judged: nine cases at a ratio of 1.0000 with every sample inside its rounding bound, and white_diffuse refused by name; the clean re-bake passed all ten. Both fixes went into the judge's selftest as plants, and a plant must be strong enough. The first consistency check only asked that the bad case fail: it passed its plant, then refused every case of the real bake, because one black render pooled with the rest made every case look inconsistent. The plant now requires the bad case to be refused alone, and the check compares each case with the per-texel median of its surface's OFF renders.

The window protocol

Scope: one Unity behaviour, measured in the owner's own editor. Precondition: a probe and its judge are written, and a window spec names the probe, its inputs and its outputs. Minimal guarantee: the owner's editor is left as it was - every record and guard file md5-held, the probes removed, nothing replaced. Success guarantee: the fact file is written with the Unity version it was measured on. Trigger: a rule the conversion needs is not measured.

The probe runs in the game owner's own editor, which is in use. A window is built so it cannot cost the owner anything:

  1. Idle gate. Start only after 600 s with no cursor movement and no key or button (wait_quiet.ps1); a launcher whose wait was killed does not start.
  2. Presence watch. A watcher writes one line the moment the owner returns; every later step checks it and stops.
  3. The editor lock. One file (.opus-tools/.locks/unity-editor.lock) names who holds the editor; a window refuses to start while anyone else holds it.
  4. Compile headless first. The probe is type-checked against the project's editor assemblies (typecheck.py --editor --extra) before it is dropped in. A probe that does not compile never enters the project.
  5. Nothing is replaced. A window refuses to start when its fact file or trigger already exists, and records the md5 of every existing fact file before and after: a bake that touched another rule's evidence is visible.
  6. Wait for the real compile. The editor assembly's timestamp must change and Unity's isCompiling flag read false; the probe's name must be in the rebuilt DLL.
  7. Trigger, wait, collect. A trigger file starts the probe; the window waits for the fact file with a timeout.
  8. Play mode only when it must. One short Play, entered and left by the window, with isPlaying checked inside the probe (edit mode never ages a TrailRenderer, so that law needed Play).
  9. Take it out. The probe and its .meta are deleted and the editor recompiles until no trace of its name is left in the DLL.
  10. Read the console. console_check.py --reset before, console_check.py after: new errors stop the work.

A window never answers a dialog it did not open.

The owner comes back. At any step the window leaves Play first, then takes the probes out (step 9); nothing else runs. Branches from step 2.

All of this is one runner, and a window is a data file - the probes, the inputs copied in, the trigger and the outputs expected, never a script cloned from the last window:

py -m u2ue --project <game> window check <spec.json>    # every refusal judged now; nothing touched
py -m u2ue --project <game> window run <spec.json>      # waits for the quiet, then runs steps 1-7 and 9-10 above
{"label": "x6", "probes": ["EffectPhotoProbe"],
 "inputs": [{"from": "<lane>/x6/effect-photo-list-x6.tsv", "to": "effect-photo-list-x6.tsv"}],
 "trigger": {"file": ".RUN_EFFECT_PHOTO", "lines": ["list:effect-photo-list-x6.tsv", "record:effect-photo-unity-x6.json"]},
 "outputs": ["effect-photo-unity-x6.json"], "wait_seconds": 900}

The project names the Editor folder a probe is dropped into (unity.probe_dir) and the files whose md5 must hold (unity.guard). A probe places a real prefab only through ProbeSpawn (the game's own spawn composition, or the prefab as authored, named), which the runner drops in with it; probe_spawn_gate.py refuses a probe that instantiates one itself. The runner's selftest drives the whole flow against a simulated editor, including the owner returning after the compile, and a mutation run on it killed all 8 of its mutants (copies of the runner with one deliberate fault each, every one of which the selftest must fail; Chapter 14 has the method). Play mode (step 8) is not in the runner yet: a probe that needs it still has its own script.

From a bake to the build

A measured rule is not copied into the converter as a constant. At build time the converter re-derives it from the bake through the same judge (for example, the sub-emitter frame rule through vfxport/subframe_rule.py), so a rule that stops holding stops the build instead of drawing wrongly. u2ue check --only facts lists every bake with the Unity version it was measured on, against the project's unity.version (the second game, on 2026-10-15; the count grows with every bake):

py -m u2ue --project <game> check --only facts
  163 measured Unity bakes; this project is Unity 2021.3.21f1
       163 measured on Unity 6000.3.16f1    UNVERIFIED for Unity 2021.3 - re-measure where it matters
  163 of 163 rules this project's build uses were measured on another Unity: its report must not call them measured for it

A rule measured on another Unity is still used (the build runs), but the report must not call it measured for your project. Whether to re-measure is your decision; the probes and judges are the means.

The laws measured so far

Every row is a fact file in shared/conformance with its judge. A selection, to show the kind of rule that has to be measured; check here before you measure one again:

law what Unity does judge
sub-emitter frame the frame a sub-emitter's particle is born in and the position it inherits vfxport/subframe_rule.py, sub_frame_rule_check.py
node shear the order a turning mesh or billboard (a camera-facing quad) particle's rotation and a non-uniform node scale are applied nodeshear_rule_check.py, nodeshear2_rule_check.py
shape scale what the Shape module's own scale does to a particle's birth point and direction shape_scale_judge.py
non-uniform motion a local particle moves unscaled and is drawn through the node's whole transform, scale included nonuniform_motion_judge.py, nonuniform_world_judge.py
ring buffer past its lifetime a ring-buffered particle lives on, its age held, until it is replaced ringbuffer_check.py
mesh alignment a mesh particle's drawn frame under each render alignment, and the frame a view-aligned rotation turns in meshalign_judge.py, alignview_judge.py, alignspin_judge.py
TrailRenderer width, colour and U (the texture coordinate along the trail) run on the distance fraction from a head vertex at the transform; on a moving frame the oldest point is dropped while the NEXT point's age exceeds time, then a point is added; a still trail freezes; the tail is drawn at the position time ago, clamped to the oldest segment trailrend_judge.py, trailrend2_judge.py, trailrend3_judge.py; the whole law replayed by U2ue.Runtime.TrailLaw's test (72 / 72 frames, 15 / 15 meshes)
Timeline control a controlled object is off before its clip, simulated at the clip's time less its start delay, off after timeline_judge.py
point light a URP point light's term on a lit surface is URP's formula exactly (the 0.96 diffuse, the sRGB decode, the range window), through the game camera's full-screen pass lights_judge.py (ten of ten cases at a ratio of 1.0000 on the clean bake)
scene lighting the sun, the 27 ambient coefficients and the default reflection cube (every face of every mip) URP lights a scene with litinputs_judge.py
Quaternion.Euler turns Z, then X, then Y, about the fixed axes u2ue/transform.py selftest

Writing a new probe

  1. Copy the nearest probe in vfxport/unity_probe/. Keep its shape: an [InitializeOnLoadMethod] that hooks EditorApplication.update to poll for its trigger file, one fact file out, and an error field in that file rather than an exception.
  2. Record what you will judge, not what is convenient: every frame's raw positions rather than a summary.
  3. Write the judge and its plants; run --selftest.
  4. Run the window. Commit the fact file, the probe, the judge and the window spec together.
  5. Make the converter re-derive the rule from the bake, and register the judge's selftest (Chapter 18).

The measurement tools

Two kinds of measurement feed the converter: what Unity ACTUALLY draws (the bakes above, under shared/conformance), and what Niagara actually does with a module input, measured in headless Unreal. Every converter rule cites one of them. "check" says whether u2ue check --only selftests runs the tool's own selftest.

The window plumbing. u2ue window run <spec.json> (above) waits on two gates, both PowerShell scripts in the lane part:

tool part what it does
wait_quiet.ps1 lane waits until nobody has touched the mouse or keyboard for the quiet period: the cursor has not moved and no key or button went down
wait_presence.ps1 lane waits until someone touches the machine: the cursor moves, or a key or button goes down. The Windows idle timer (GetLastInputInfo) cannot answer this where injected input resets it constantly, so the gate polls the cursor position and the key states itself

The Unity-side judges (in vfxport/unity_probe/, beside their probes), each reading a bake. The rows use Shuriken's own settings: a system simulates in Local or World space, and its scaling mode (Hierarchy, Local or Shape) decides which scale reaches its particles; Chapter 11, "Space, scale and the transform chain", explains both.

tool what it reads off its bake check
particle_facts.py the particle facts a general probe measured -
cube_facts_check.py which texel Unity samples along a direction, on a cube texture -
shapes4_facts_check.py where real emitters' shapes put their particles, and with what velocity, as Unity emits them -
nodeshear_rule_check.py the ORDER Unity applies a turning mesh or billboard particle's rotation and a non-uniform node scale in -
nodeshear2_rule_check.py the second node-shear bakes, holding the rule on more cases yes
viewshear_rule_check.py the view-aligned shear rule, against measured quads -
trailscale_check.py a trail's WIDTH under a uniform Hierarchy node scale: whether the node scale reaches the width yes
sub_frame_rule_check.py a Birth or Death sub-emitter child's emission frame, against every measured case yes
shape_scale_judge.py particle by particle, what Unity does with the Shape module's own scale yes
force_scale_judge.py which rule a force, or a World-space velocity over lifetime, on a LOCAL system follows under scale -
wstretch50_judge.py a World stretched billboard and a Local-scaling child under a scaled root -

The Unreal-side probes: what Niagara does, read before the converter relies on it.

tool part what it measures check
v4_module_inputs.py scene_tools a Niagara module's own input names, types and DEFAULT values, READ off the engine yes
v4_probe2.py scene_tools which write route a colour curve takes -
u1e_shape_probe.py effects_tools how Niagara's cylinder location composes "Non Uniform Scale" with "Cylinder Axis" -
u1e_trail_probe.py effects_tools how Niagara carries a trail, before the converter writes one -
u1e_trail_real_probe.py effects_tools real trail emitters built through the converter's own code, read back -
u1e_trail_diag.py effects_tools why a probe's ribbon got no particle -
u1e_random_probe.py effects_tools whether two of the converter's per-particle randoms are INDEPENDENT of each other in one particle -
u1e_burstp_trial.py effects_tools what a BUILT system's probability burst does over many plays -
u1e_burstp_judge.py effects_tools judges those plays and writes what Niagara did as facts yes
u1e_bursttrain_probe.py effects_tools whether a burst train is written the way the converter predicts -

A second game supplies nothing here: the probes measure the ENGINES. It re-runs the windows for the features its effects use that no bake covers yet, and for any rule that matters on its own Unity version (each bake records the version it ran on, above).

9. Verification and gates

Who this is for: the porting developer - after this chapter you know the four rules every check in a port follows and which gate applies each, and you can prove a converter route offline and hold a whole build to Unity on numbers with u2ue conform.

Four rules

  1. Read or absent, nothing else. Every value is READ (from a file, with where it came from), MEASURED (Chapter 8), or named ABSENT with the reason. A tool that cannot read a value stops and names it. It does not substitute a default and carry on: a build that silently drops a value is worse than one that fails, because the failure is invisible and later reasoning builds on it.
  2. A gate must be able to fail. Every gate carries planted defects (its --selftest) and must refuse each. A gate that has only ever passed cannot be told apart from one that is switched off. When a gate's scope is widened, its plants are run again.
  3. Verify with both. Numbers and pictures each lie in their own way. On the reference port a render where the whole scene went black scored better on a pixel metric, because dark geometry stopped hiding a bright backdrop. The data must prove itself first; then the metric and the image confirm it. Neither one diagnoses on its own.
  4. A miss is unknown. The toolkit's code readers are lexical: they match the code's text, not its compiled meaning. A call through an interface, a delegate, reflection or a UnityEvent is invisible to them, so "no caller found" means unknown, never unused.

The gates

gate what it refuses run by
every tool's own selftest the tool's planted defects u2ue check --only selftests
vfxport/yaml_field_gate.py a Unity field, in a module this project enables, that the reader neither reads nor excuses with the values it may take u2ue check --only gates
vfxport/ir_field_gate.py an IR field the converter neither uses nor lists in DELIBERATELY_UNREAD with its reason u2ue check --only gates
the measured rules' versions a rule measured on another Unity, reported as measured (it is named UNVERIFIED) u2ue check --only facts
layer_gate.py, host_gate.py an engine reference in the model; a platform member outside the hosting folder u2ue check --only model
vfxport/converter_trace_gate.py a converter change that alters what an existing route writes (every engine call recorded against a stub unreal, working copy against a commit) by hand, before a converter change lands
vfxport/whole_trace.py a new route that changes more, or less, than the emitters it names by hand, per route (Chapter 7)
v4_msg_gate.py a write the engine refused: Niagara's SetParameter logs an unknown name or a wrong type as an error and returns false, and the message is saved inside the package (the system's saved asset file) per trial, over the built packages
the read-back judges a built system whose particles, per 1/60 s frame, do not match the rule they were built from u2ue read
u2ue parity a model row that differs between runtimes beyond its characterised allowance Chapter 5
scene_fidelity_gate.py a moved hierarchy, material, texture, light or placement in an imported level Chapter 6

Proving a route offline

The converter writes through Unreal's Python API, so a route can be proved without an engine: run the converter against a recording stub (a stand-in for the unreal module that records every call and its arguments), once at a reference commit and once with the change, and compare every call.

py -m u2ue --project <game> tool whole_trace.py <ref> <work>                # switch off: identical calls on every emitter
py -m u2ue --project <game> tool whole_trace.py <ref> <work> --on VFXPORT_<NAME> --expect-only KEY:PSFILEID
                                                                            # switch on: exactly the named emitters change

<ref> and <work> are the full paths of two copies of the converter (build_niagara.py): tool runs the tool in its own folder, and the tool refuses to start outside the facade because it reads the project's paths. Each KEY:PSFILEID names one emitter: an effect key and the file id of its ParticleSystem (the id that object carries inside its prefab file), which every later record pairs emitters by.

This is what lets a route land behind a switch while other builds are running: it is proved to change nothing until it is turned on.

Conformance over every key, data first

Scope: every effect key of a project at once, Unity's particle state against what the built Niagara systems compute. Precondition: the keys are built in Unreal, and the owner allows a Unity window. Minimal guarantee: an emitter one side does not have is named UNPAIRED, never dropped. Success guarantee: every emitter OK, or its verdict named with its numbers. Trigger: a build is to be held to Unity on numbers before its photos are looked at.

Photos compare one draw at a time. This compares every emitter of every key on numbers, in one pass:

  1. Write the cases: py -m u2ue --project <game> conform cases --name <run> writes, from the project's IR, one probe case per key (its prefab placed by the game's own spawn, the seed pinned, read from a restart at each time), the Unity window that runs them, and the Unreal read of the same keys.
  2. Read Unity: py -m u2ue --project <game> window run <run window spec> runs the one generic probe in the owner's idle editor (Chapter 8).
  3. Read Unreal: py -m u2ue --project <game> trial run <run read spec> reads the keys' built systems at the probe's own step, 0.02 s, with no new build.
  4. Compare: py -m u2ue --project <game> conform diff --unity <record> --unreal <record> --report <file> pairs each emitter by its system's file id and reads BOTH sides at Unity's sample times only. The Unreal read has every frame and Unity only its few samples, so otherwise a particle born and gone between two samples would be counted against the port. A first birth is compared by the frame it is first drawn on, and Unity's ages are put in real time by the emitter's simulation speed (the converter rescales each emitter to real time). Each emitter reads OK, LATE or EARLY (first drawn on a later or an earlier frame), COUNT (the live counts apart at a sample by more than 1 or 5 %, whichever is larger), BIRTH UNREAD (no age can be read: an infinite lifetime), UNPAIRED, or NO DATA (neither side drew a particle at the times read). The report is stamped with the judge's own id.
  5. Keep the score: py -m u2ue --project <game> conform latest reads the newest stamped report of the run the project names in conform.standing_run, and refuses one that another judge made (re-run the diff). u2ue cycle (the recurring check of every pillar) trends its share of OK emitters, so a converter change that loses some goes red; a denser run is another measurement, made the score only by changing that field.
  6. Name each miss: py -m u2ue --project <game> conform classes --report <file> names a LATE, EARLY or COUNT row only when the converter's own build note on that emitter (joined by file id), or a measured signature (a miss already measured and named, such as one warm-up tick late), agrees with it in direction AND size. Every other row is listed as the work, never passed. A class names the WHOLE row: the judge records every sample of a COUNT row, and a class reads them all, never the first difference alone. Some misses are the probe's own: Unity's emission covers the half-open step (from its start up to, but not including, its end), so a burst due exactly on a sample time is drawn one step later than the port draws it. That is a capture artefact, never a game frame; the reference port measured it on every such sample of two runs before naming it. A particle at its exact end on a sample is the same instant from the other side, and is named only when each side's own particles say so (Unity's remaining lifetime, the port's age, both at the end). A probe can be blind. The reference port's case probe, restarting the simulation for each sample, never drew a sub-emitter of a sub-emitter (0 of 284). Stepped at its 0.02 s default, it drew 15 the PORT does not draw, which the restart read had hidden as no data, while seven the port draws stayed empty; stepped at the game's own frame step (1/60 s, conform cases --step 1/60), those drew too, their counts matching the port's. Check a class built on a probe's silence against a second way of looking, with the probe stepping the way the game steps, before calling the port right or wrong.
  7. Follow the class, not the key. A verdict a whole class of emitters shares is one rule to measure or one route to fix: the reference port's first such read found every non-prewarmed burst (one whose emitter does not start as if it had already run a loop) born one warm-up tick late, 121 of 121. That first read of every key also found the judge's own faults before the port's: a first birth taken from every Unreal frame against four Unity samples, and infinite lifetimes passing as OK because an undefined age compared as no difference. Make the judge prove itself with plants before believing what it says about the port.

Looking at the result

Photos are checked by eye, and the toolkit makes that part of the process instead of a courtesy:

  • u2ue photo renders Unreal frames at Unity's sample times; u1e_photo_sheet.py lays each effect's Unity and Unreal frames side by side.
  • A sheet is LOOKED at before a route is called done. A frame where the capture itself failed (a black frame, a missing texture stream) is labelled as a capture artefact and never counted for or against the port.
  • A screenshot route returning ok proves bytes were written. Open the file.

When a gate goes red

Three rules, each with its measured case in Chapter 14 ("Rules that keep tests honest"): check that the thing moved before believing it broke (a gate that walks one folder reports what the port moved as ABSENT); never re-record a baseline to make a red gate green; re-run a test that another worker changed minutes ago before investigating it.

10. Metrics and reports

Who this is for: the porting developer - after this chapter you can build the acceptance page, read each number it prints by its definition, quote it honestly, and find the tool behind each read-back, photo and report.

Every number the toolkit prints is computed from a record on disk, with its denominator and its definition. A number it cannot compute is printed ABSENT with the record it needs. An input older than the newest build is marked STALE, because it describes builds that no longer exist.

The acceptance page: u2ue report

py -m u2ue --project <name> report [--out FILE]

One HTML page per project, built from that project's records: the IR summary, every key's build verdict, the read-back sweep (every read-back check run over every built system's read), the photo sheets, the gap roots, and the decisions only the owner can make, each with its evidence. It reads what is there: a key never built reads "never built", and a pass not yet run reads absent. A project's first report, before any build, already lists every key it will have to account for. In port, the report is the last automatic stage; port then stops for the owner's decisions the page asks (Chapter 4).

The numbers: u2ue metrics

py -m u2ue --project <name> metrics [--json FILE]
number definition
keys the project's effect keys (its IR summary), each with the verdict of the record the page chose for it
drawn an emitter whose build log carries modules: it draws in Unreal
absent, as Unity absent exactly as in Unity, each by a measured or read rule: the game never starts it, Unity never fires it, Unity draws or emits nothing there itself, or Unity has no particle to draw it on
absent, gap every other absent emitter: Unity draws it and Unreal does not. Charged to its root (an absent parent's children to the ancestor absent for its own reason), so a root's count is what porting it brings back
coverage drawn / (drawn + gap): of the emitters Unity draws, the share Unreal draws
measured drawn emitters with no SUBSTITUTED note: drawn by a rule measured against Unity, not a named stand-in
data the read-back sweep: per check, emitters checked and failures, summed
image the photo screen: pairs compared, pairs flagged, and of those how many are labelled capture artefacts
machine the chosen records' own build seconds per key, summed and as a median
routes the converter's switches flipped default ON with their evidence, and those deliberately OFF with what each waits on

The emitter numbers are the acceptance page's; the metrics verb never recounts them, because two programs that count the same records will not agree. Measured on the reference port: three drafts of the coverage figure were wrong before the one quoted (99.4 %, 91.3 % and 91.8 %), from reading a stand-in's "draws nothing" as Unity's, counting skipped logs as drawn, and missing the measured sub-emitter chain rule. So the definitions are part of the claim: a number quoted without its definition is not one.

Sample output, from the reference port on 2026-10-17 (the gap roots cut to the first; the page lists every one). The figures move as builds land: Appendix A reads the records of 2026-10-15, two days earlier. A number that cannot be trusted says why on its own line: data reads STALE (older than the newest build ...) when a build is newer than the read-back sweep, and image reads ABSENT: no sheets listing ... - the photo pass has not run.

keys      674: BUILT 673, IR REFUSED 1; 673 drawn, 197 of them with a named gap; 514 from the acceptance rebuild
emitters  drawn 7810 | absent: gap 641 (Unity draws them, Unreal does not), 375 absent exactly as in Unity (Unity NEVER fires it
          267, not started when the game spawns it 58, Unity draws nothing here itself 25, which the game never starts 14, Unity
          emits nothing here itself 7, so Unity has no particle to draw it on 4)
coverage  92.4 % of the emitters Unity draws are drawn in Unreal (7810 / 8451)
measured  86.4 % of the drawn emitters carry no stand-in (6745 of 7810; 1065 drawn with a named SUBSTITUTED note)
          800 named parts absent on drawn emitters (a module or field each, on the page)
gap roots (what porting each brings back - emitters, keys, the root's reason):
            31   20  non-uniform scale (..) on an ENABLED shape; the location modules take one radius, so it is REFUSED rather than
machine   32.8 h of build time over 673 keys, median 100 s a key (the chosen records' delete..finalize seconds)
data      26973 emitter-checks over 26 checks, 8 FAIL (99.97 % hold)
image     673 sheets, 164 flagged for a big difference (24 of them ONE DRAW, 34 GRIDTICK - the capture, not the port); 75.6 % unflagged
routes    98 verified switches read default ON today, each with its evidence row (111 TABLE rows - a switch read in two files has
          two; 3 switches with a row still read OFF: VFXPORT_FX35_ORBIT, VFXPORT_FX35_WORLD, VFXPORT_SUBSHAPEPOS); 11 switches
          deliberately OFF, each with what it waits on (toolkit-wide, not per project)

In image, ONE DRAW marks a key whose look hangs on a few random particles, and GRIDTICK a burst born exactly on a photo time: frames where a difference is the capture, not the port (Chapter 11, "Photos are draws; their dates mix").

Porting speed: u2ue tempo

py -m u2ue --project <name> tempo [--json FILE] [--since YYYY-MM-DD]

How long each converter route took from its first line of code to its verified flip, read off git. A route is one switch; first code is the earliest commit whose added lines carry the switch's name; flipped is the earliest commit in which every file that reads it reads it default ON. Read the median with the batch lines beside it: in the sample below (the reference port, 2026-10-18), the routes flipped alone or in a commit of fewer than five routes took a median of 2.9 h, and the 58 flipped together in batch releases 40.9 h. That wait was the release's, not the route's, so tempo reports the two apart.

py -m u2ue --project <game> tempo
u2ue tempo - the toolkit's verified routes, first code -> verified flip, from git (definitions: u2ue/verbs/tempo.py)
  VFXPORT_AMESH                  first code 2026-10-10T17:41 (c369e881)  flipped 2026-10-12T13:47 (70ee5858)     44.1 h
  VFXPORT_BILLMESH               first code 2026-10-10T17:45 (e9e0addb)  flipped 2026-10-12T13:47 (70ee5858)     44.0 h
  ...
  VFXPORT_BUILTINMIPS            first code 2026-10-14T11:30 (83a9ce50)  flipped 2026-10-14T17:30 (74aa80ed)      6.0 h
  ...
  97 routes: first code -> flipped, median 28.4 h (quartiles 3.5 / 43.5 h); flipped per day: 2026-10-12 50, 2026-10-13 22, 2026-10-14 14, 2026-10-16 11
    flipped alone or in a commit of fewer than 5 routes: 39 routes, median 2.9 h
    flipped in a batch release (one commit flipping 5+ routes): 58 routes, median 40.9 h - the wait is the release's
  1 switches carry no OFF stage on record (first code already reads them default ON): VFXPORT_CULLFRONT
  NOT FLIPPED / ABSENT VFXPORT_FX35_ORBIT: vfxport/build_niagara.py (reads it default OFF today)
  NOT FLIPPED / ABSENT VFXPORT_FX35_WORLD: vfxport/build_niagara.py (reads it default OFF today)
  NOT FLIPPED / ABSENT VFXPORT_SUBSHAPEPOS: vfxport/build_niagara.py (reads it default OFF today)

Routes are the toolkit's, so tempo reads the same git history for every project; a switch with an evidence row that still reads OFF is listed, never counted as flipped.

What tempo does not measure, so that it is never implied: the time from finding a defect to its first code, the agent's tokens, and the machine's build hours (those are metrics).

Reading the numbers honestly

  • Quote a number with its denominator and its date: "92.4 % coverage" in the sample above means 7810 of the 8451 emitters Unity draws, on 2026-10-17.
  • Coverage is not fidelity. An emitter that draws can still draw wrongly; measured, data and image are the numbers that speak to fidelity, and image needs the photos to have been looked at.
  • A gap is a named, owned item, not a failure to hide. The report lists every gap root with the reason the converter gave.
  • A check that ends without a result is UNCOUNTED, never clean. u2ue metrics and the check sweep list such runs apart; on the reference port a crash once went into the sum as zero failures and hid a real one.
  • Expect a long tail of gap roots. In the 2026-10-17 run sampled above (Appendix A names the same root), the biggest root brings back 31 of the 641 gap emitters (a non-uniform scale on an enabled shape, over 20 keys). No single route closes the gap: work down the report's list of roots.

What the numbers do not measure yet

"Percent identical" is never one number. It is a family of four, each answering its own question: coverage (does it draw), measured (is it drawn by a measured rule), data (do its particles follow Unity's numbers), image (do the frames agree, capture artefacts excluded and counted). One combined "identical" figure would hide which of the four moved.

Not measured yet, and how it will be:

  • Porting speed on a fresh game. The second game's run, timed from extract to its first report and on to each coverage milestone, with the agent's own wall-clock and token count beside the machine hours. Today u2ue tempo times routes, not a game, and py -m u2ue --project <name> metrics [--json FILE] sums build hours, not a porter's.

Read-back and checks: the tools

What a BUILT system really holds (renderers, module inputs, the particles of a simulated frame, mesh properties), read back and held to the IR's prediction, emitter by emitter. Every check names what it could not judge, and every check has a PLANT that must make it FAIL. A plant that depends on a read (--plant on the read-back checks) needs that trial's OWN read pair, never an older one: a check once paired with the newest build FAILED for that reason alone. "check" says whether u2ue check --only selftests runs the tool's own selftest.

tool part what it does check
u1e_niagara_readback.ps1, u1e_niagara_readback.py effects_tools a built system's particles read back through the engine's simulation cache -
u1e_niagara_readback_check.py effects_tools a built system's per-particle dynamic material parameters, read back and held to the IR -
u1e_color_size_readback.py effects_tools every built system's particles per 1/60 s frame: does it draw Unity's MEASURED start colour and size rules (what u2ue read runs) -
fx17_readback.ps1 effects_tools the read-back of every built system, in parts of about 60 systems -
fx18_parts.py effects_tools the read-back part lists for a whole rebuild, made from the build records themselves -
u1e_meshprops_read.py effects_tools what a built system's mesh renderers hold -
fx17_checks.py effects_tools every read-back check over every read-back part yes
u1e_color_size_check.py effects_tools the colour and size read-back held to Unity's measured rules -
u1e_fin9f_check.py effects_tools before an hour-long build, every NEW engine write that build depends on, each checked first -
u1e_flip_check.py effects_tools every built sprite flip held to Unity's measured rule -
u1e_flipbook_check.py effects_tools every built flipbook emitter's frame held to the measured rule -
u1e_fx37v_check.py effects_tools every built emitter whose build note names one route, read back and held to Unity's rule for it: the pattern every per-route check below follows yes
u1e_mirror_check.py effects_tools every mesh emitter the build drew mirrored plant per trial
u1e_nodeshear_check.py effects_tools every emitter built with the node-shear route plant per trial
u1e_stretchshear_check.py effects_tools every emitter built with the stretched-billboard shear route plant per trial
u1e_viewshear_check.py effects_tools every emitter built with the view-shear route plant per trial
u1e_vmeshnu_check.py effects_tools every mesh emitter drawn with the non-uniform node route plant per trial
u1e_subemit_check.py effects_tools every built sub-emitter child held to Unity's measured rule -
u1e_survivor_child_check.py effects_tools every Collision sub-emitter child of a SURVIVING parent plant per trial
u1e_trail_check.py effects_tools the ported trails held to Unity's measured trail rules plant per trial
u1e_simulates_check.py effects_tools does every built system actually SIMULATE in its read-back yes
v4_msg_gate.py scene_tools the converter's OWN failures read off the SAVED package (Chapter 9) yes
v4_write_gate.py scene_tools every name the converter writes, checked against the module's own input table yes
niagara_read.py scene_tools the renderer and module-input state of a SAVED Niagara system -

v4_write_gate.py is the example of a static check that knows its own reach: it can type only the writes its table covers (92 of the converter's 383 on 2026-10-13, u2ue/README.md), so its selftest passes while the gate itself exits 1 for that coverage. The authority it defers to is v4_msg_gate.py, which reads what the engine actually refused. A second game supplies nothing here beyond its build records.

Photos and contact sheets: the tools

A frame of each built effect beside Unity's, one contact sheet per effect, and a screen for the pairs that differ most: the image half of "verify with both" (Chapter 9), because a metric alone has lied.

tool part what it does
u1e_fx_photo.py effects_tools a FRAME of a built effect without the game: the system spawned alone and drawn at each time (what u2ue photo runs)
u1e_photo_sheet.py effects_tools one contact sheet per effect: Unity's frame (from the photo probe) above Unreal's
u1e_sheet_screen.py effects_tools which photo pairs differ BIG: a screen that says where to LOOK first, never a verdict

A second game supplies its camera framing for a photo.

The acceptance report: the tools

The acceptance sentence is the game owner's to write. The reference port's was: every effect the game fires draws in the Unreal build as Unity draws it, and every gap is named. One report holds it: per key the verdict, the named gaps, which absences Unity shares (never fires, draws nothing itself), and the decisions only the owner can make.

tool part what it does check
report_build.py lane the acceptance page from the records (what u2ue report runs) -
u1e_gap_census.py effects_tools every NAMED gap in the effect build, from the build records themselves -
u1e_never_fires.py effects_tools every IR emitter Unity NEVER spawns a particle of, by the measured sub-emitter chain rule yes

A second game supplies its own acceptance sentence.

11. Shuriken to Niagara, in depth

Who this is for: the porting developer working on effects - after this chapter you can say why an effect draws differently in Unreal, read what the converter writes for each Shuriken module, and close a gap yourself, from the census to the flip.

Chapter 7 gives the effects pipeline and the route protocol as steps; this chapter gives the reasons behind each step. Read Chapter 7 first, and come back here when an effect does not draw as Unity draws it, or before you write a route of your own.

Why a purpose-built converter

No tool converted Unity particle systems to Niagara when the toolkit was started (searched 2026-08-22; Appendix D gives the search and what it found). The toolkit borrows one thing from Epic: the CascadeToNiagaraConverter plugin (built to convert Unreal's own older Cascade particle systems to Niagara), whose Python API writes a Niagara stack module by module.

One finding frames the work: an effect's STRUCTURE ports automatically, its LOOK does not (the look lives in materials and shaders, "Materials and textures" below). shuriken_ir.py reads prefab YAML into the engine-neutral IR with no Unity running, and build_niagara.py runs inside Unreal and writes the systems, materials and textures; the verbs run every stage for any project ("The verbs, underneath", below).

The rules, before any command

Chapter 9 states the toolkit's rules. Effects give each one a reason of its own:

  1. READ or ABSENT, never a guess. A rule measured at one value is not known at another: a ring-buffered particle is held past its lifetime at 1/60 s and longer, and NOT at 0.005 s or under (measured 2026-10-13). A route that had extrapolated from a 1 s measurement drew a glow Unity never draws.
  2. No fallbacks. log + continue, except: pass and a default substituted on failure are the same lie, made invisible. A refusal names the emitter by its system name (the name the build logs): an IR name does not match an emitter Niagara de-duplicated.
  3. Verify with both. A read-back check can pass while the frame is wrong. LOOK at the pair sheets before calling anything done.
  4. A check that has only ever passed proves nothing. Every check has a plant, a deliberately broken input it must FAIL.
  5. A converter change is proven before it builds anything: vfxport/whole_trace.py over the whole IR, a Niagara probe where the stubbed trace is blind (compile errors, run-time kills), a trial that is read, judged and looked at, then the flip with its evidence row in patch_flip_defaults.py and a clean flip_audit (no switch a trial set still reads default OFF, unless it is named deliberately OFF: "Routes and switches", below). A new route goes behind a VFXPORT_* switch, default OFF, until its trial.
  6. One headless Unreal at a time, from native PowerShell. UnrealSharp finds dotnet by the PATH entry Program Files\dotnet\ with its trailing backslash, which a PowerShell started from Git Bash loses (Chapter 13). The Unreal verbs refuse that shell up front, and refuse while the host is busy.
  7. The owner's Unity editor is the owner's. A measurement window starts after 600 s of idle (wait_quiet.ps1 600), stops the moment the owner returns (wait_presence.ps1), leaves every fact file it did not write untouched (md5 before and after) and never answers a modal. The Unity Test Runner is never used (Chapter 12).

Why it is hard

Two models of one effect

A Shuriken ParticleSystem is one component with a fixed set of modules, each with an enabled flag and a fixed list of fields. Most fields are a MinMaxCurve or MinMaxGradient in one of four modes: a constant, a curve, a random value between two constants, or one between two curves. Unity runs the modules in its own fixed order inside its own particle step.

A Niagara emitter is a set of scripts (emitter spawn and update, particle spawn and update, event handlers), each a stack of modules, plus renderers kept apart. Each module is a graph with declared inputs, and an input can belong to one version of the module and not another, sit behind a static switch (an option fixed when the script compiles) or an inline edit condition (a flag that must be on for the input to apply), or take a dynamic input (a small graph that computes the value) or a data interface (a curve is one) instead of a value. So one Unity field becomes a module, an input name, a type, a version and sometimes a switch, and the API reports a failure at any of those by returning False rather than raising (see the traps). Niagara runs a stack top to bottom, so the converter writes modules in the order Unity runs its own.

Space, scale and the transform chain

  • Simulation space. A Local system simulates in its node's frame and the transform carries the result into the world; a World system's particles stay where they were born.
  • Scaling mode (scalingMode: Hierarchy 0, Local 1, Shape 2). Under Hierarchy Unity multiplies a particle's size by the node's whole lossy scale (its scale in the world, lossyScale), under Local by the system's own scale, under Shape by neither. A Niagara sprite's size is absolute: it is laid along unit tangents and never passes through the component's transform (NiagaraSpriteVertexFactory.ush:993, read in UE 5.7). So the converter folds the scale into the size. Without the fold every sprite draws wrong by exactly one over its lossy scale (on the reference port's first scene, 3.571 times too large under a lossy scale of 0.28).
  • Motion under a scaled chain. MEASURED (2026-10-07): a Local system moves in UNSCALED local units (start speed, velocity over lifetime, radial push, limit, drag) and the transform scales the result into the world, but gravity acts in world units. The port's frame carries the chain's turn and place, not its scale, so without a correction a scaled emitter moves at the unscaled speed (2.5 times too fast at 0.4); motion_scale in vfxport/build_niagara.py scales each local-unit input. A World system under a scaled chain takes different factors per part (the WSCALE route).

The transform chain is composed up m_Father (each Transform's link to its parent in the YAML) to the prefab root, the root's rotation included, and carried into Unreal by one fixed frame: Unreal (X, Y, Z) = (-100 x, 100 z, 100 y) in centimetres. That matrix has determinant +1, so a quaternion maps as (-qx, qz, qy, qw). Unity's Quaternion.Euler turns Z, then X, then Y about the fixed axes.

A NON-uniform node scale shears a facing quad in Unity (measured: a View-aligned billboard takes the node's lossy scale along the WORLD axes after facing the camera), which no Niagara sprite draws; the VIEWSHEAR route reproduces it in the parent material's World Position Offset. The IR's ownerScale, the axis-aligned product of the local scales, is not Unity's lossy scale diag(R^T M) where a non-uniform scale sits above a turn, so the IR also carries lossyScale and nodeMatrix. And a spawn scale on the Unreal component reaches a Local emitter's positions and a mesh but never a sprite's size (NiagaraSpriteVertexFactory.ush:923-1003): the SPAWNSCALE route writes it into the size every frame, and only a photo at the game's own spawn scale can see the rule.

Two clocks

Unity's particle clock adds each step up in float32 and tests a burst against it half-open. A Unity probe that steps Simulate on the fixed timestep runs at the project's own step (0.02 s on the reference project) while the Unreal read steps 1/60 s: the two share ages only at multiples of 0.1 s, so compare at the particles' own ages and read the step off the data.

With interpolated spawning (the converter's empty template has it), Niagara's spawn script reads every float emitter parameter LERPED by the particle's spawn fraction, so Emitter.Age read at spawn is the emission instant; integers and a short list of engine constants are not lerped (read: NiagaraHlslTranslator.cpp:5113-5153; Chapter 7 gives what this means for start values). Pick the clock to match Unity's: the lerped parameter for a start speed (read at the emission instant), the frame's end rebuilt from values that are never lerped for a start size or lifetime (read at the END of the emitting step).

Random draws

The toolkit's Unity probes pin the seed (useAutoRandomSeed = false), so a Unity frame is reproducible. Niagara's VM (the virtual machine that runs its scripts on the CPU) seeds its randoms per batch off the CPU cycle counter (VectorVMRuntime.cpp:444-446); determinism is a compile-time emitter flag the converter does not set and Python cannot reach. So no random value is compared particle for particle: the port matches the DISTRIBUTION Unity draws, measured. A random-constants start size is uniform and independent of the start rotation, speed and lifetime (a Kolmogorov-Smirnov distance, KS, of 0.018 from uniform, 2026-10-06); a TwoColors start colour draws ONE fraction for all four channels; two RandomRangeFloat inputs in one particle are independent (correlation 0.006); a value Unity holds per particle is a spawn-only random in Niagara.

The IR: reading Shuriken offline

The reader is effects_tools/u1e_ir.py over vfxport/shuriken_ir.py, with effects_tools/u1e_nested.py for nested prefabs. It reads the YAML of a project serialized as text, with no Unity running. Chapter 7 shows an IR excerpt, Chapter 21 its format.

Per effect key it holds: every emitter's modules, each value with its mode and a readAs saying how it was read; the renderer (mode, alignment, rendererEnabled, meshes, pivot, sort); the material, its shader resolved by guid and its blend READ as numbers; the emitter's place in the prefab (prefabPos, prefabRot), ownerScale, lossyScale and nodeMatrix; the system's file id (_psFileID), by which every later record pairs it; the sub-emitter links; and the natural length, or null with the reason.

Reading MinMax values

At serializedVersion 2 the constant modes do not use the curves: minMaxState 0 is scalar, minMaxState 3 the range [minScalar, scalar], and the curves stored beside them are stale (a random-constants range's order is in the traps, below). Unity writes a float field holding 0 as 0, which a YAML loader returns as an integer: type a value by the field it replaces.

File ids

Every object in a Unity YAML file carries a file id, the number after & on its header line, by which other objects reference it (a negative file id is one of the traps, below).

  • Nested prefab instances. An object inside a nested instance has, in the outer file, the id (instance id XOR source object id) AND 0x7FFFFFFFFFFFFFFF, and references inside the expanded objects re-key the same way (measured 2026-10-07 on every placeholder of 15 expanded prefabs). The outer file's "stripped" placeholders, read as objects, look like extra root transforms. u1e_nested.py expands each instance, applies its modifications, checks every placeholder against the formula and drops it. A prefab variant's root is an instance of its base, so the same expansion reads it.
  • Legacy records. Class 1001, the YAML class of a nested prefab instance (!u!1001), is also a pre-2018.3 prefab's own "Prefab" record (&100100000, m_RootGameObject or m_IsPrefabParent, no source); Unity 2018.1 and 2018.2 wrote it as m_SourcePrefab {fileID: 0} with m_IsPrefabAsset. It is kept, never expanded.
  • Removed and added objects. The effect reader applies m_RemovedComponents and m_RemovedGameObjects (the scene reader is Chapter 6's); added GameObjects and components are refused by name. A nested MODEL instance (an FBX) has no YAML: it is left out and named unless the IR depends on it.
  • Shader Graph shaders are cited with a NEGATIVE file id (a sub-asset of the .shadergraph file). A regex expecting a positive integer reported "no shader" for 1,930 of the reference port's 1,999 effect materials (read 2026-09-29).
  • Built-ins. The guid 0000000000000000f000000000000000 is the Editor's unity_builtin_extra, whose names are read off that file (set unity.editor). The built-in Default-Particle material is file id 10301, its texture 10300 (64 x 64 RGBA32, 7 mips).

What the game decides, not the prefab

What starts when an effect spawns is the game's rule. Unity's own rule plays a system whose Play On Awake is on; a game's pool may do more (the reference port's pool also plays the first system's whole subtree). The adapter names the rule (Chapter 18), the IR records each emitter's spawn start, and an emitter the game never starts is absent in both engines.

The field gates, and what they cannot see

yaml_field_gate holds every key of every ENABLED module (and the ParticleSystem and renderer) to the reader: read by shuriken_ir.py ON THAT MODULE, or excused with the reason and the values it may take, re-checked on every run. ir_field_gate holds every IR field to the converter: named there, or listed in DELIBERATELY_UNREAD with its reason. Both run in u2ue check --only gates.

The gate keys a field by its module path - ColorModule.gradient, never the bare name gradient. Its ReaderReads reads the reader's source with ast from emitter_ir through every call it makes, and credits a read only to the module the reader reads it from; an idiom it cannot follow credits nothing, so the gate names that field rather than pass it. Until 2026-10-20 it matched a NAME, and every field the by-speed modules serialize (enabled, gradient, curve, range, separateAxes, x, y, z) is a name the reader reads for another module or writes as an IR key, so an enabled by-speed module passed unseen. The reader still reads no Color, Size or Rotation by Speed module (the table below), so a project that enables one now sees each of its fields named UNACCOUNTED until the reader and the converter port it. The gate's selftest proves both directions on a real prefab of the project: each by-speed module switched on fails, and a reader that reads one passes.

What the gate still cannot see: it reads each source prefab's OWN documents. A system that lives in a nested prefab instance is checked only when its prefab is itself a source of the IR, and an instance's overrides never are.

Module by module

"Measured" means a Unity probe baked the rule (Chapter 8) and the converter re-derives it at build time; SUBSTITUTED is a stand-in the acceptance report counts; ABSENT is not drawn, with its reason.

Unity module Niagara state
Main: duration, loop, delay, prewarm, max particles EmitterState (Life Cycle Mode Self), loop delay, system warm-up, a cap route measured; the cap SUBSTITUTED (one frame late)
Emission: rate, bursts, rate over distance SpawnRate (a curve where authored), SpawnBurst_Instantaneous per burst, SpawnPerUnit measured; a random rate over distance ABSENT
Shape SphereLocation V1 / V2, BoxLocation, CylinderLocation, spawn assignments per shape measured per shape; the rest named
Main: start values InitializeParticle, AddVelocity, AddVelocityFromPoint measured, with the instant each is read
Colour / Size / Rotation over Lifetime ScaleColor (RGB and alpha separately), ScaleSpriteSize / ScaleMeshSize, SpriteRotationRate or mesh orientation measured
Colour / Size / Rotation by Speed none not read (see the field gates)
Velocity over Lifetime, Force, Limit, Gravity update assignments, AccelerationForce, VortexForce, Drag, GravityForce, SolveForcesAndVelocity measured where planned; the rest named
Noise CurlNoiseForce SUBSTITUTED: Unity's noise is not measured
Collision its own route on the measured subset, else CollisionQuery measured, else SUBSTITUTED
Renderer sprite renderer (alignment, facing, pivot), mesh renderer, sort hints measured per mode; allowRoll SUBSTITUTED
Texture Sheet Animation SubImageIndex per the measured frame rule Grid, whole sheet, lifetime and FPS modes
Trails a ribbon emitter fed by a location event measured
Sub Emitters event generators on the parent, handlers on the child Birth and Death measured; the rest named
Custom Data Dynamic Material Parameters measured per stream layout
Lights point lights on the effect (Chapter 7) per-particle Lights module ABSENT
External Forces none SUBSTITUTED (wind zones are the scene's)

Emitter state and the loop

EmitterState's "Life Cycle Mode" defaults to System, under which an emitter IGNORES its own loop behaviour, duration and delay while every write reports success: the converter sets Self, and writes the loop delay with its inline edit condition on. Unity prewarms an EMITTER; Niagara warms the whole SYSTEM and floors the warm-up to whole ticks. The port warms the system by the longest prewarmed loop, written half a step over, and delays every other emitter to start where Unity starts it. Unity's run-once window is half-open while Niagara's loop runs one frame long, so a run-once rate emitter grows one extra particle (67 of 93 on the reference port, 2026-10-07): the converter kills a birth at or after the window's end inside the spawn script. Niagara's ParticleState kills a particle a hair before its lifetime where Unity still draws it: the converter kills on Age > Lifetime. A start lifetime of Infinity becomes float32's largest finite value, named.

maxParticles is a cap Unity refills in the step a particle dies. Niagara takes its spawn counts from the count at the frame's START (NiagaraEmitterInstanceImpl.cpp:1300-1313), so the port refills one frame late: exact where nothing is replaced, a named substitute elsewhere. Without the route nothing holds the cap at all (one emitter kept about 50 alive where Unity keeps 1). Its room and frame-start count are INTEGER parameters, because a float one reaches the spawn script lerped. Named, not ported: cullingMode, stopAction (the host decides), useUnscaledTime, and the ring-buffer modes outside their measured range.

Rate, bursts and rate over distance

A rate curve is the scalar times the curve at the loop's normalized time (Chapter 7). Niagara's first tick after activation adds nothing to SpawnRate, so the converter preloads the spawn remainder with rate x DeltaTime at emitter spawn: k / rate at any frame rate. Each burst is its own SpawnBurst_Instantaneous with an Int32 count (how Niagara names the second is a trap, below). A repeating burst is one module per cycle or a burst train; one that repeats forever is refused; a probability fires the whole burst, one roll per firing. A burst exactly on a step's end in Unity's half-open float32 clock fires on the NEXT step (0.25 s ends step 15 at 1/60 and fires on 16; 0.5 s stays on 30): the BURSTLAG route puts every off-grid burst's first frame on Unity's step. Under a system warm-up every non-prewarmed burst is born one warm-up tick late (178 of 178 on the reference port), which the WARMBURST route corrects. Chapter 21's switch table gives each route's default.

Rate over distance is particles per unit the SYSTEM travels, one at each crossing (measured). SpawnPerUnit takes the spacing exactly, places each particle up to one frame of travel AHEAD of Unity and at large steps misses the first and last crossings (named). A random rate over distance is ABSENT: Unity draws a new rate every step. A sub-emitter child's distance emission is its PARENT's travel.

Shapes

  • Cone. Unity's Cone emits from its BASE, a disc of radius r (radiusThickness 0 is the rim), along the generator through each point, tilted atan(u tan a) at fraction u of the radius (measured). ConeLocation fills from its apex and has a Cone Length and no radius, so the converter uses CylinderLocation at height 0, at its latest version, turned to the axis, and writes the direction.
  • Sphere and Hemisphere. SphereLocation V1 adds its Offset in simulation space, unturned; V2 with "Offset Coordinate Space" Local turns it with the component. Both sample uniformly in volume (measured).
  • Circle, Donut, Arc. A Random-mode arc spread snaps particles to multiples of spread x 360 degrees; a Loop arc or donut moves at 360 x speed x birth time, wrapped at the arc; a BurstSpread burst of N sits at i / (N - 1) of an arc, i / N of a full 360.
  • Edge. A BurstSpread burst of N lies at i / (N - 1) along [-r, r]; a Loop edge moves at u = Frac(speed t / r), which only a bake at a radius other than 1 could tell.
  • Mesh. Particles start on Unity's own vertices, P = T + R (S . v), the start speed along the turned vertex normal.
  • Rectangle. A moving Rectangle's start velocity is along the shape's turned +Z (measured within 6e-8).

A disabled Shape module's transform does nothing in Unity (measured); an enabled one's rotation turns the emission axis, not the particles, and its position is composed under Hierarchy scaling and refused under the others. Named where unmeasured: randomPositionAmount outside its measured case, a Random radius spread on a shape other than a Circle, animated radius modes.

Start values, colour, size and rotation

InitializeParticle carries the start lifetime, size, colour and rotation ("Sprite Rotation Angle" does nothing unless "Sprite Rotation Mode" is "Direct Angle (Degrees)"); AddVelocity the start speed along the shape's direction; AddVelocityFromPoint a radial push. A start size or lifetime curve is read at the END of the emitting step, a start speed curve at the emission instant (Chapter 7).

Colour over lifetime goes through ScaleColor's "RGB and Alpha Separately" arm, Scale RGB from a VectorFromCurve and Scale Alpha from a FloatFromCurve: the only arm Python can build, and the closer mapping, since Unity authors RGB and alpha as separate gradients. Keys built in Python get automatic tangents unless they go through unreal.InterpCurvePointFloat with CIM_CURVE_BREAK and FXConverterUtilitiesLibrary.keys_from_interp_curve_float; a curve data interface defaults to a 128-sample lookup table, and use_lut False evaluates it exactly. Size over lifetime is ScaleSpriteSize or ScaleMeshSize, each rebuilt from the spawn size so nothing compounds. Rotation is SpriteRotationRate on a sprite; a mesh renderer reads only its mesh orientation, so a mesh's spin goes there.

Motion, collision and noise

Velocity over lifetime (linear, orbital, radial, speed modifier) is written as ordered update assignments where its plan is measured; otherwise a stand-in (a constant acceleration, one vortex) is SUBSTITUTED and every part it leaves out ABSENT. A pasted module can land BEFORE the solver (Niagara fixes up dependencies on paste), hence the assignments. Gravity falls world-down even in a Local emitter, velocity first, as in Unity; limit and drag use the unscaled size and local speed (measured). The VM's vector length uses an ESTIMATED reciprocal (VectorVMRuntime.cpp:1912: 999.875 for 1000), so a rule that depends on a length uses a dot product and a power of 0.5. Noise is a CurlNoiseForce of the same strength and frequency, SUBSTITUTED.

A Planes collision with every slot unassigned collides with nothing in Unity, so nothing is written. Where the measured subset holds (the touch at radiusScale x size / 2, the bounce, the slide, a lifetime loss of 1, World behaving as Planes, a Collision child's burst on the touching step) the converter writes its own route; any other collision is a CollisionQuery, SUBSTITUTED. GenerateCollisionEvent drops a touch slower than its "Velocity Threshold" (1 cm/s by default) unless the threshold is written -1.

Renderers

  • Billboard. Unity drops the camera's ROLL; Niagara's facing modes keep it, and no stock dynamic input gives the per-particle camera forward that would drop it: allowRoll is SUBSTITUTED.
  • Stretched billboard. The long axis is size x lengthScale. The legacy pivot moves the quad 2 x pivot.y x size forward whatever the length (measured at lengthScale 1 and -1, after a bake at 2 could not tell the rules apart). A negative Niagara sprite size mirrors the IMAGE, never the quad. Velocity alignment zeroes the sprite rotation; custom alignment faces the camera POSITION, not its plane.
  • Horizontal and Vertical. A Horizontal billboard's DIAGONAL is the particle size (side size / sqrt 2) and Niagara's custom facing needs a facing vector written. A Vertical billboard draws the same upright quad under View, World, Local and Facing alignment (measured), side size / sqrt 2.
  • Mesh. The import is REFUSED unless it matches the file per corner: position, UV and winding (an FBX's axis signs turn Unreal's import and not Unity's mesh; a box check cannot see a 180-degree turn). Unity multiplies a mesh's vertex colour into the particle colour (measured); Niagara's VertexColor is the mesh's own colour and 1 on sprites and ribbons, so Particle Color x VertexColor is exact on all three. Niagara corrects culling for the COMPONENT's determinant only: a mirrored mesh is safe only two-sided.
  • Render mode None draws no particle (a trail-only emitter draws its trail); m_Enabled 0 draws nothing. The descending sort is spelled CUSTOM_DECENDING in 5.7's Python.

Texture sheet animation

Measured, re-derived at build time: frame = floor(N x frac(f + s)), N = tilesX x tilesY, f the frame over time (a constant, a random held per particle, scalar x curve(frac(cycles x normalized age)), or fps x age / N in FPS mode) and s the start frame. The converter writes Particles.SubImageIndex itself (SubUVAnimation has no start-frame override). Named where unmeasured: Speed mode, a Sprites-list or single-row sheet, flipped sheets, a partial UV channel mask.

Trails

A trail is a Niagara RIBBON emitter beside its parent, on the route Epic's Cascade converter uses: a location event generator on the parent and a handler on the ribbon spawning one point per event. Measured in Unity: the head vertex IS the particle; each point lives the lifetime fraction x the particle's lifetime; width and colour run from head 0 to tail 1; the trail's colour over lifetime is taken at the particle's CURRENT age and tints the whole trail. A ribbon point cannot read its parent, so each carries its parent's normalized age, lifetime and draws in the event payload, on slots the receive module actually applies. Niagara never scales a ribbon's width (NiagaraRibbonVertexFactory.ush:862) while Unity scales a Hierarchy trail under a scaled parent: the TRAILSPAWN route writes it. A textureScale other than 1 is SUBSTITUTED.

Sub-emitters

The frame a Birth or Death child emits in, MEASURED on 117 cases (vfxport/subframe_rule.py, judged by vfxport/unity_probe/sub_frame_rule_check.py):

R = Cw . LookRotation(u, up = (0, |u.z|, 1 - |u.z|)) . Cl . S     the parent particle moving at the trigger
R = Cl . S  (world-fixed)                                         the parent particle still

Cw is the child system's world rotation, Cl its OWN local rotation (so its local turn counts twice), S its shape rotation, and u the parent particle's total velocity at the trigger in the child's frame (Birth after the parent's first step, Death as it died, Collision after the bounce). A rule fitted on axis-aligned cases alone fitted a WRONG rule exactly; oblique, rotated and grandchild cases broke it. A child's own GameObject position plays no part. In Niagara the child is an event-spawned emitter. A Birth child of a Birth- or Collision-spawned middle NEVER fires in Unity (measured) and is counted apart; an unported child is EMITTER-ABSENT with its reason, never drawn as an ordinary emitter. The event traps are listed below.

Custom data and vertex streams

Custom Data reaches a Unity shader only through the renderer's Custom Vertex Streams. Measured: a Custom1.xyzw list packs uv0.zw = Custom1.xy and uv1.xy = Custom1.zw, default streams give uv0.zw = (0, 1), and Custom Data curves run ONE simulation step behind the particle's age. The converter writes Dynamic Material Parameters above ParticleState, which keeps that lag, and supports a layout only where a control case read it. STREAM_SLOTS_READ names the slots each shader reads, and a read slot on an unmeasured layout is refused; a shader not listed is taken to read none, so each newly ported shader adds its row.

What Niagara has no equivalent for

Each is a named stand-in, an emulation or a refusal: refilling a cap in the step a particle dies; a billboard that drops the camera's roll; a 4-channel colour curve from Python; per-emitter prewarm (emulated); Unity's sheared quad (emulated in the parent material); deterministic random draws from Python; a single-particle event mode (5.7 has Every Particle and Spawned Particles); an event-spawned child whose curves are not applied twice (the console variable that stops it breaks trails); and what an asset pack's custom shader does beyond blending, which needs a hand-authored parent per shader family. Unity's noise field, external forces, culling modes and unscaled time are named for another reason: their Unity rule is not measured yet.

The converter's machinery

vfxport/build_niagara.py writes Niagara stacks through FXConverterUtilitiesLibrary in a real Unreal editor process, one stage per Unity module in the order Unity runs them (Chapter 7 lists the twenty stages, Chapter 18 shows their code). A route of your own lands in one stage, behind its switch. What follows is what a route meets when it writes.

Writing one value

  • add_mod refuses a module asset that is not there: create_asset_data on a missing path still returns an asset.
  • setp tries each candidate input name and returns whether one TOOK, honouring set_parameter's boolean, and records every miss in the build report's param_misses.
  • VERSION pins a module's script version per module; some modules answer differently at 1.0 and at their latest graph.
  • Propagated static switches. UNiagaraGraph::FindStaticSwitchInputs (NiagaraGraph.cpp:2143-2166) returns the module graph's own static switch nodes AND every function call node's PropagatedStaticSwitchParameters, renamed to their propagated name when set; SetParameter accepts both. A reader that walks only the switch nodes calls the second kind "not declared" while the engine takes it: ShapeLocation V2's "Rotation Mode" lives on a function call node, and one build wrote it on 57 emitters with 0 refusals. scene_tools/v4_module_inputs.py lists a module's declared inputs off the shipped .uasset, propagated switches included; read it before calling such a write wrong.
  • Module names. A module is found by NAME anywhere in the stack, so every extra instance a route adds gets its own name (the traps, "Events, sub-emitters and trails").
  • One input object, one parent. A script input handed to two parents is lost from one; build a fresh input per use.

Names, rules and notes

Niagara renames a clashing emitter handle, and every event names its source by the REAL handle (the rule is in the traps). vfxport/niagara_names.py reproduces the engine's naming (59 of 59 systems exact against a full build, 2026-10-06), assigns every name before the emitter is added, and avoids the reserved namespace names (an emitter called "Particles" stops the system compiling).

A measured rule is not a constant in the converter. cap_rule, trail_rule, flipbook_rule, sub_emitter_rule and their siblings read the bake (shared/conformance/color-size-facts.json and others) at build time and re-derive the rule from the case's own control; a rule that stops holding makes its route refuse by name.

vfxport/shuriken_size.py holds the size arithmetic with no engine in it, so the converter inside Unreal and a measurement in plain Python import one rule (two copies is how the first scene's size bug survived). It folds the scaling mode in (size_scale returns None to REFUSE when the scale it needs is absent), applies the measured side of a Horizontal or Vertical billboard, the stretch length, the non-uniform arm (a 188 x 1476 cm shaft written as a 200 cm square was the bug it fixed) and the VIEWSHEAR plan. py vfxport/shuriken_size.py runs its selftest.

The acceptance page (lane/report_build.py) counts a stand-in only when its field note contains SUBSTITUTED, so a runtime gap is written "SUBSTITUTED : ...". An absent emitter carries its reason in the record's absentEmitters.

Routes and switches

A route is one Unity behaviour the converter ports, behind a switch named VFXPORT_* (the converter's) or U1E_* (the effect tools'). A new switch is read os.environ.get("VFXPORT_<NAME>", "0") == "1": OFF unless set. extract, build, read and photo remove every VFXPORT_ and U1E_ variable inherited from the shell and name them, so an ordinary build is the defaults and nothing else; a trial sets its route's switches for its build step only.

The evidence table and the flip

vfxport/patch_flip_defaults.py holds the evidence once, in TABLE: per row the file that reads the switch, the switch, and the evidence that it may flip (the trial, its read, its judge and plant, the sheets looked at). A flip rewrites the read to os.environ.get("VFXPORT_<NAME>", "1") != "0" (still switchable off with =0) and marks the line with the date and a pointer to its row; it adds no line. A switch read in two files flips in both or not at all: the tool refuses, exit 2, while any read of a flipped switch still defaults OFF anywhere in the code trees.

py vfxport/patch_flip_defaults.py --list              every row: its switch, its file, its evidence
py vfxport/patch_flip_defaults.py --dry <ROW> ...     what the flip would change; nothing written
py vfxport/patch_flip_defaults.py <ROW> ...           the flip: atomic per file, compiled before it replaces the file

Chapter 21's converter switch table is generated from that table and the code, with each switch's state today.

flip_audit and the state of a route

lane/flip_audit.py compares every switch a trial set with its default in the code as it stands, and flags a trial switch read default OFF anywhere (unless DELIBERATE_OFF names why) and a switch whose read sites disagree. DELIBERATE_OFF is evidence too: a route measured SLOWER (a data-processing conversion context made the finalize 1.5 times slower), a route that waits on another (an arc placement exact at the frame's end while every later burst cycle is born a tick late), a route measured DIFFERENT from Unity, a switch for probe builds only.

py -m u2ue --project <game> tool flip_audit.py

A route is ON when EVERY file that reads its switch reads it default on, DELIBERATELY OFF when flip_audit names what it waits on, and OFF otherwise. A table row is evidence that a switch MAY flip, not proof that it did: u2ue metrics counts a route as flipped only when every file reads it on today, and counts switches, not rows.

The route protocol, from evidence to flip

Take the next gap from the acceptance page's absent emitters by root, ordered by what porting each brings back:

  1. Census with today's converter, offline, over the whole IR: which emitters the route would gain, and what refuses them NEXT. Check that Unity draws them at all (never fired, never started, renderer off, emission measured 0 are not gaps).
  2. Find the measurement you already have: the cases of every shared/conformance/*-facts.json that names the module. If the rule is not measured, measure it in one window the owner allows (Chapter 8), never from documentation.
  3. Write the route behind its switch, default OFF, and prove it with whole_trace.py: off, the same engine calls on every emitter of every IR; on, exactly the predicted set changes. Add a Niagara probe where the stub is blind.
  4. Trial: a data file (keys, the route's switches, a content root of its own, the steps), run from native PowerShell. Build the gained keys, resave, read, run the route's judge AND its plant, photograph, LOOK. A photo difference counts only past two draws' spread.
  5. Flip with its evidence row, then a clean flip_audit.py. Keys built before the flip are rebuilt as a delta.
  6. Write it down: the route's numbers and its commit in your work list, and any new trap.
py -m u2ue --project <game> tool whole_trace.py REF.py WORK.py --on VFXPORT_<NAME> --expect-only <key>:<psFileID>,...
py -m u2ue --project <game> trial plan <spec.json>       every command each step would run; nothing runs
py -m u2ue --project <game> trial run <spec.json>        one Unreal at a time; the code parts run from a snapshot
py -m u2ue --project <game> trial stop                   stop at the next step boundary
py -m u2ue --project <game> judge --prove                every judge a trial runs; exit 1 when one has no plant that refuses

A trial runs from a SNAPSHOT of the code parts, so an edit to the live converter while it runs cannot change what it runs. A change to a tool that a running build loads is a patch script, proven on a copy and landed after the build (Chapter 7).

When an agent stops and asks the game's owner: a product decision (a shader family with no Unreal port: port it or name it; an effect that differs by design), anything that would run in their live editor, a second project's Unreal host, and anything outward-facing. Ask one precise question, then take the next gap.

Porting a gap, in depth

Census first, and count what the NEXT gate refuses

A refusal family ranked by its FIRST reason misleads: a plan function returns at its first failing condition, so a label covering 27 emitters looked like one route; lifted, all 18 targets hit the next blocker and the route drew nothing. Lift the one gate in a COPY, run the whole trace, count what passes the next gate. A build record's reason is the converter's of its day: census with today's converter. A parked route's reach moves when other routes land: re-measure it after each.

Measure before you write

A probe in vfxport/unity_probe/ builds each case as a fresh ParticleSystem, steps it with Simulate at 1/60 s and bakes what it reads to shared/conformance/<name>-facts.json. When particle data cannot answer, read what the RENDERER draws: ParticleSystemRenderer.BakeMesh gives a sheet frame, whether a particle is drawn at all, and a mesh particle's drawn extent. The judge (<name>_judge.py) is written BEFORE the bake, derives every rule from the case's own control, and its --selftest refuses a planted bake. The window is a data file run by u2ue window (Chapter 8), with console_check before and after. Wait on the file the probe ACTUALLY writes, and never let a measurement write a file the converter reads while a build runs: give it its own output name (a trigger's out: line). When the judge disagrees with the real bake, suspect the judge first. Then the rule goes into a checker the converter calls at build time: ringbuffer_check.rules() raises when a rule stops deriving from its bake.

Before measuring, do step 2 of the route protocol (list the cases of every shared/conformance/*-facts.json that names the shape or module): an edge burst of 5 had been baked while a converter note still called it unmeasured. Fold measurements into one window, since each costs the owner's editor two recompiles, and check every asset path its trigger names.

Measure at more than one value, and read the drawn result

A bake at a parameter's unit value cannot tell a law that scales with it from one that does not: an edge loop at radius 1 could not tell Frac(speed t) from Frac(speed t / r), and the game's edge had radius 4. Measure at two values of everything a law could depend on.

What Unity reports is not always what it draws. An aligned particle's rotation3D (alignToDirection) is start + E(d) per axis, drawn by Quaternion.Euler(-rotation3D), where an unaligned one is drawn by Euler(+rotation3D) (measured). Read a drawn turn off BakeMesh of an asymmetric mesh, never off the particle's fields. When the judge's candidate rules all fail, say so, read the rule off the columns it printed, and confirm it on bakes made before the rule was seen.

Find WHICH emitter, then read the shader

When an emitter draws but its colour or brightness is wrong, isolate it first (u1e_fx_photo.py with U1E_PHOTO_ISOLATE=<handle>, about 30 s an emitter): three explanations of one dim effect were each tested on an emitter named by eye, the wrong one. Then compare the port's material body with Unity's GENERATED shader line by line (shared/conformance/generated-shaders/<name>.shader, written by the facts probe's sg: line from the Shader Graph importer), and prove a suspected slip offline: evaluate both formulas over the material's own texture, decoded as the engine samples it. One ramp branch with the wrong remap hid in 337 emitters wherever two ramp colours were close; one dim effect found it. And read what Unity samples, not the source file: its imported texture is in Library/Artifacts, found through Library/ArtifactDB (Chapter 12).

Photos are draws; their dates mix

An Unreal photo is ONE random draw; Unity's is a fixed seed (useAutoRandomSeed = false). A key whose look hangs on a few random particles reads lit or dark by luck: a route was nearly reverted for a "regression" that a second draw of the SAME build reproduced. An A/B on photos needs its noise floor: two draws of each side, and a move is real only past both sides' spread and 0.5 % of the light. u1e_randdraw_census names the one-draw keys from the IR alone (one to three births before 1 s with a wide spread, or a burst probability below 1); the sheets print ONE DRAW on them. A burst born exactly at a photo time is the capture's: Unity's float32 clock reaches 0.1 exactly at step 6 but 0.9999997 at step 60, so a burst at 1.0 s fires a step later in Unity, and the sheet marks the frame GRIDTICK. A sheet pairs each Unity time with the NEWEST Unreal photo at that time, so a trial that photographed 0.1 to 1.0 s keeps an older build's later frames; the sheet marks a frame older than its asset STALE.

Hold Unity's times as float32; read summaries

A judge that compared a double time put a 0.1 s burst a step early, and Unity's fixed-step Simulate ran on 0.02f, not on the timestep it reported (0.0199999921): read the step off the data. whole_trace.py prints at most six DIFF records, and an ON set of 14 read as 6 until --expect-only was run: read a tool's summary line, never count its rows. Quote numbers from the page: u2ue metrics runs the page's builder and prints ITS summary (a recount once printed 91.3 % where the page said 92.3 %). u2ue tempo reads each route's first code to its flip off git.

Materials and textures

Blend is a number

Blend mode decides most of an effect's look, and it is NOT in the shader name. Asset-pack effect shaders (UberFXSG, HS_Blend_CG, HS_Distortion and their kin) carry blending as numeric material floats. In a first sample of 51 materials: 19 src=One dst=One (additive), 16 src=SrcAlpha dst=One (additive, non-premultiplied), 14 src=One dst=OneMinusSrcAlpha (premultiplied) and 2 src=SrcAlpha dst=OneMinusSrcAlpha (classic alpha). A name-based guess got 14 of 51; the numeric read gets all of them. The rule: DstBlend == 1 (One) is additive; SrcBlend == 1 (One) is already premultiplied, so the emissive is NOT multiplied by alpha again. Across the reference port's 1,999 fired effect materials (read 2026-09-29): 969 additive, 904 classic alpha, 41 opaque, 13 premultiplied and 61 with no numeric blend, which are refused rather than guessed. A converter that assumed additive would get about half wrong and still produce something that looks like particles: the failure that survives a screenshot.

The largest family's author (scene_tools/vm1_author.py) keys its blend table on (src, dst): (5, 1) additive, (5, 10) alpha blend, (1, 0) opaque, (1, 10) premultiplied; any other pair is refused by name. Unreal 5.7's additive blend DOES weight the emissive by Opacity (BasePassPixelShader.usf:2261): an instance that multiplies by alpha as well squares it, and low-alpha glows go near invisible.

One parent per shader family

What a custom shader does beyond blending (soft-particle depth fade, distortion, camera-facing tweaks, ramps) has no Unreal equivalent, so the bill is one hand-authored Unreal parent per distinct Unity shader, not per material; every material of the family is then an instance with its values read off the .mat. On the reference port one family was behind 593 of the 724 effect prefabs the game fires (81.9 %, read 2026-09-29) and the next three took it into the high nineties. The parents' authors are scene_tools/vm1_author.py (the largest family) and one module per family in effects_tools/ (legacy alpha-blended particles, matcap, two-sided, blend-distort, dissolve, toon, electricity). Verify a new parent before any frame: the largest family's was held to an independent evaluation of the same shader, at a repeat floor measured from two separate editor processes, with a plant that broke one character of its HLSL. A family with no parent yet is refused by name, its emitter absent, the rest of the effect built.

Reads a picture would have got wrong, each found in shader source:

  • URP's Unlit pass never reads Emission (UnlitPass.hlsl:85); a shader driving BaseColor and Emission from one node would have doubled in brightness had both been ported.
  • A branch reading TEXCOORD1 reads a Unity custom vertex stream, not a second copy of TEXCOORD0.
  • HDR colour properties (m_ColorMode 1) are already linear in the .mat.
  • Unity samples every texture through its _ST (uv x _ST.xy + _ST.zw); a port that reads the tiling and never applies it drops it silently.
  • _Cull 1 culls FRONT faces in Unity when the shader lets the material override culling; built one-sided in Unreal it drew the faces Unity culls (the CULLFRONT route builds it as Unity draws it).

Variants and built-ins

A material VARIANT (m_Parent) serializes only what it overrides; the rest is its parent's, recursively. Read alone, a (0, 0, 0, 0) alpha channel selector picks no alpha and the emitter draws nothing while every check passes. scene_tools/vm1_read_materials.py resolves the chain, and the build refuses any input still unset: a property absent from the .mat is never evidence that the shader default applies. A built-in texture is a texture, not "no texture": a reader that treats a texture not on disk as an unassigned slot samples white (one such material drew as a 20 m orange square). Built-ins are read offline off unity_builtin_extra.

Unity's imported texture

Unity samples its IMPORTED texture: it fills RGB under alpha 0 (alpha is transparency), averages mips as an unweighted LINEAR box (Unreal's TMGS_SimpleAverage), resamples a non-power-of-two source to a power of two, and caps the size. effects_tools/unity_tex_artifact.py reads that import offline and validates every decode against the source (Chapter 12 gives how, and the trap it guards). Unreal's embedded Python has no PIL or numpy: such reads run in system Python and hand the build a derived file and a manifest. Two routes use them: the mips and mip bias of each .meta (an Unreal import is mip-less unless the route is on; a grainy look where Unity's is smooth is minification aliasing, which the .meta answers before any shader term) and Unity's stored RGB under transparent texels.

Proof

Read back every frame

u2ue read simulates each built system headless and reads its particles per frame through Niagara's sim cache (a recording of a system's particles, frame by frame; Chapter 13 gives how): position, velocity, colour, size and age every 1/60 s, or at Unity's probe step for a like-for-like read of positions. Three rules:

  • Built is not compiled, and compiled is not simulating. BUILT means saved with no converter error; a system never resaved in a fresh process reads nothing ("No valid simulation data"; Chapter 13 gives why). u2ue build and the trials resave, and effects_tools/u1e_simulates_check.py fails a system that never simulates, which no other check can.
  • NOT JUDGED is not a pass. A 90-frame read cannot see a child that fires at 2.28 s; read that system longer.
  • The record is not the asset. A caller can ignore a refusal function's False, so the record says "absent" while the asset draws. effects_tools/u1e_renderers_read.py reads what a saved system carries.

Checks on the saved asset, and judges with plants

Five checks, each with its plant: scene_tools/v4_write_gate.py refuses, before a build, a write no module declares; the other four read the SAVED package. scene_tools/v4_msg_gate.py refuses a package the engine logged a refused write into; scene_tools/v0_readback.py compares the saved fields with the IR; v4_curve_check.py compares the colour and size curves key for key; scene_tools/v2_dup_gate.py refuses a module or renderer added twice. effects_tools/u1e_names_gate.py proves the emitter names held, and effects_tools/u1e_material_errors.py tells a material's wiring-time compile messages from a real error.

Each read-back check in effects_tools/u1e_*_check.py holds one measured rule against the read and carries a plant. A check of the bound alone passes a route that does nothing: a cap check ("never above the cap, and the cap reached") passed a route that kept one particle and never spawned another, until it required Unity's refill. Ask what a route that does NOTHING would score, and plant the property the route changes. u2ue judge --prove fails a judge with no plant that refuses.

Photos

u2ue photo takes Unreal frames at Unity's sample times (0.1, 0.3, 0.6 and 1.0 s by default) for the pair sheets (Chapter 13 gives how the capture is made like for like). Unity's reference frames come from a float target (the unity_hdr photos): an 8-bit target clamps each draw before blending and under-draws HDR-boosted materials. Calibrate the Unreal capture like any instrument: an 8-bit sRGB target loses everything under about 1/510 linear, so the pair captures half floats to EXR and encodes them as Unity's target does (effects_tools/u1e_exr.py; a known constant must come back 255 / 188 / 137). A photo at an emitter's own start delay or lifetime is a step-edge frame in both engines: compare just off the edge.

Conformance against Unity's particle state

u2ue conform compares every emitter of every key on numbers (the procedure is Chapter 9). Its Shuriken specifics: Unity has no age field, so an age is startLifetime - remainingLifetime, undefined for an infinite lifetime (the first judge passed those as OK because NaN compares false). Unity's clock at a sample is the probe's own: Simulate at a simulation speed takes whole fixed steps in float32 and drops the rest (measured on 860 of 860 samples). Emitters are paired by file id, never by name, and both sides read at Unity's sample times only. A probe can be blind: one that restarted the simulation for each sample never drew a sub-emitter of a sub-emitter, which stepping at the game's own 1/60 s did.

The verbs, underneath

The effects route covers Shuriken ParticleSystem prefabs; extract lists VFX Graph assets and scene-authored particle systems by name as NOT COVERED. The game's code is Chapter 5, scenes and UI Chapter 6.

A project is one file, u2ue/projects/<name>.json (Chapter 3): the Unity project (serialized as TEXT), optionally its Editor (unity.editor), what the effects are, the Unreal host and content root, and where the work goes. py -m u2ue --project <game> info (u2ue info) opens every path and exits 1 when an input is missing: fix the project file before any other verb.

The adapter's three answers

With "adapter": "unity_project" the toolkit answers the game questions itself: every prefab holding a ParticleSystem is an effect, Unity's own rule decides what starts at spawn, and the Unreal host is busy only while an Unreal runs. Write an adapter in u2ue/adapters/ (subclass UnityProject, override ONE method) only when the game's code changes one of those answers, for example when its effects are the ones an ability table names (Chapter 18). py -m u2ue find <words> searches every document, tool, rule and route at once.

extract and check

extract builds the guid index in order - Assets/..., the project's embedded Packages/, then Library/PackageCache (package shaders resolve there) - then the keys, then one IR file per key. It exits 1 unless every key came out as an IR file or a NAMED refusal, every IR parses, and every Assets/... path an IR names exists in this project's tree. What a second project hits: legacy Prefab records (m_SourcePrefab {fileID: 0}), nested MODEL instances, m_RemovedComponents, package shaders, built-in shaders named off the Editor's unity_builtin_extra (set unity.editor). Measured on a second, unrelated game (2026-10-13): 60 keys gave 56 IR files (189 emitters) and 4 refusals, each by name.

check runs the toolkit's selftests and your project file's own, then yaml_field_gate and ir_field_gate, the measured rules' Unity versions and the engine-free model's gates. Exit 1 means do not build: a red field gate is an unread Unity field, and it will be a silent gap. check --only facts names the Unity version each measured rule was measured on against the project's unity.version; on another major.minor the rules are UNVERIFIED for this project, the build still runs, and metrics says so.

build, read and photo

build --dry first: the plan and the host's state. Then the asset-name table (two Unity files of one stem must not land on one Unreal asset), fx17_build.ps1 running u1e_build headless in batches, and a resave of only the systems THIS build made (U1E_RESAVE_ONLY). The record is <records>/u1e-build-<TAG>.json: per key its verdict, every emitter's modules and field notes, every absent emitter with its reason. Chapter 13 gives each of the three verbs' options and how it runs.

read writes <records>/rb_<TAG>_<N>.json, the input of every read-back check (effects_tools/u1e_*_check.py); a system that captured no frame is named, and the usual cause is a build never resaved. photo takes the frames, then u1e_photo_sheet pairs them with Unity's frames of the same times (<photos>/unity_hdr, taken by the effect photo probe in the project's own Editor, the owner's call). Read what differs against the record's notes first: a TwoColors start colour draws a different random colour in each engine, and a burst on the photo's own frame shows a step early or late. The verb is judged by its capture record, never the tool's exit.

report, metrics, tempo

report writes the acceptance page: every key's verdict, every absent emitter by reason and by ROOT, every stand-in, the read's sweep, the photo screen, and the owner's decisions. metrics prints the numbers, each from a record with its definition and age: coverage, measured, data, image - a FAMILY, never one "percent identical". tempo reads each route's first code to its flip off git. Quote metrics, never a recount, and treat a first number that looks too good as a bug until shown otherwise (a first coverage draft said 99.4 %: a stand-in's "draws nothing" had been read as Unity's).

Where things are

The converter is vfxport/build_niagara.py with shuriken_size.py, its proofs whole_trace.py and converter_trace_gate.py; the build, read, photo and check tools are in effects_tools/; the queues, trials and report builder in lane/; the material parents in scene_tools/; the Unity probes and judges in vfxport/unity_probe/, their bakes in shared/conformance/. The facade is u2ue/ (Chapter 18 gives how it finds each part).

The traps

Each was hit for real: the trap, then its fix. The timing traps (Life Cycle Mode, the edit condition, prewarm, the run-once end, the first tick, the lerped float, the cap) are explained under "Module by module" and not repeated here.

Unreal's Python API

  • The CascadeToNiagaraConverter plugin must be ENABLED in the .uproject, or FXConverterUtilitiesLibrary and NiagaraEmitterConversionContext do not exist.
  • The conversion API asserts without Slate (-run=pythonscript dies with Assertion failed: CurrentBaseApplication.IsValid()), and -ExecutePythonScript quits when the script returns, before the tick loop runs. Use a Content/Python/init_unreal.py startup hook in a real editor, guarded by an environment variable so opening the project by hand stays inert.
  • The editor world does not tick actors (a stock system as the control drew nothing either). Enter Simulate (editor_play_simulate(), then get_game_world()) or advance the system yourself, as the sim cache read does.
  • print() does not reach stdout: write results to a JSON file.
  • Copy Epic's call patterns from Engine/Plugins/FX/CascadeToNiagaraConverter/Content/Python: Paths.py has the module and enum asset paths, every ModuleConversionScripts/*.py the exact input names.
  • Arity. CreateScriptContextArgs(assetData, [1,0]) is positional; find_or_add_module_script(name, args, category) RETURNS the script context; add_renderer(name, propsInstance) wants an instance; show_only_component(comp) takes one argument; the pool enum is NCPoolMethod, not PSCPoolMethod; unreal.Rotator is positional (roll, pitch, yaw), so use keywords (unreal.Rotator(pitch=p, yaw=y, roll=r)).
  • set_parameter reports a failed write by RETURNING FALSE. UNiagaraScriptConversionContext::SetParameter logs ENiagaraMessageSeverity::Error and returns false for an unknown name or a wrong type. A setp that ignored the bool lost 80 writes over 19 systems from 8 causes, each reported as applied (2026-09-29). The failures are INSIDE the saved asset as UNiagaraMessageDataText exports, and scene_tools/v4_msg_gate.py prints them and exits 1 on any error.
  • Read the module's declared inputs; never guess (v4_module_inputs.py, off the shipped .uasset). Guessing got wrong: the non-uniform size is Sprite Size; ScaleColor has no Scale Color; ConeLocation has Cone Length and no radius; SubUVAnimation has Number Of Frames; VortexForce has Vortex Force Amount; Spawn Count is an Int32 and Scale Factor a Vector2f.
  • A module can be VERSIONED, and CreateScriptContextArgs(ad, [1,0]) pins the OLD graph: Init builds its name map from the graph of the version handed to it. ScaleSpriteSize (bVersioningEnabled True, two graphs) refuses Uniform Scale Factor and Scale Sprite Size Mode at 1.0 and takes both at latest; ScaleColor takes Scale Mode at 1.0 and refuses it at latest. Pin the version per module; a file read that merges a package's graphs is WEAKER than the engine.
  • No 4-channel colour curve from Python: unreal.NiagaraDataInterfaceColorCurve does not exist in 5.7's Python, the factories stop at CreateVec4CurveDI (a Vector4Curve the engine refuses by name), and ColorFromCurve and Vector4FromCurve want the missing class. Use Scale RGB from a VectorFromCurve (its curve is create_vec3_curve_di's class) and Scale Alpha from a FloatFromCurve. The keys are readable after all: v4_curve_check.py compares FRichCurve.Keys with the IR.
  • The finalize pastes twice: the emitter and the system context each paste every staged module and renderer and empty neither list, so calling both built every emitter TWICE. Finalize at the system only.
  • A conversion context alive at exit asserts (call unreal.SystemLibrary.collect_garbage() at the end; never save a throwaway probe system), and a headless editor can crash in its embedded browser (launch with -nocef).

Reading Unity's files

  • Constant MinMax modes do not use the curves (scalar, [minScalar, scalar]). shuriken_ir.minmax multiplied the scalar by the first key: a tornado whose start rotation was exactly pi / 2 lay on its side, flares read 24 to 30 m/s against Unity's 30 to 70, a 0.3 s delay read 0. Every IR constant carries readAs, saying how it was read.
  • A signed file id breaks the split: --- !u!95 &-745123763528618581 did not match &(\d+); the pattern takes -?.
  • A renderer can be off: m_Enabled 0 draws nothing; the IR carries rendererEnabled, and no renderer is added.
  • A prefab's emitters have places: each emitter's transform in the prefab, root rotation included, goes into the emitter (prefab_frame, when the IR carries prefabRot).
  • Unity names an FBX mesh after its MODEL node, not its geometry; and Unreal imports through Interchange (not the legacy importer), whose unit conversion is on by default, so a metre file imports at 100 times its raw numbers. Check every import per corner.

Shapes, bursts and lifetimes

  • Unity's Cone emits from its BASE; ConeLocation fills from its apex, its axis +X by default. CylinderLocation 1.0 has no "Cylinder Axis" (refused inside the package): ask for the latest graph (location_cylinder_u1).
  • Two bursts are two SpawnBurst modules: Niagara names the second SpawnBurst_Instantaneous001, and the duplicate gate's --expect-build u1e-build.json accepts a twin only when the system holds exactly the burst modules the build asked for.
  • An INFINITE lifetime left the whole system dead in a game run, nothing in the log; a report of each system's active flag and bounds found it.
  • A random-constants range is serialized min > max as often as not: mm_range(...) returns the pair as serialized; take max() for the longest.
  • Compare counts over TIME, not only per frame: on the reference port 72 of 130 measured rows were off while every per-frame check passed (2026-10-07). Compare at Unity's sample times.
  • A named stand-in is still a stand-in (an unported child drawn at the origin), and the shot must not wait for the effect to END (photograph each effect at its peak).

Events, sub-emitters and trails

  • Niagara RENAMES a clashing emitter handle, comparing names with the FName number stripped: X_2 clashes with X, as does a distinct name such as ArcaneNoise_Lazy_Disco_1, and 001, 002 are appended. A renamed parent was never found by its events and the system read back empty. niagara_names.py names every emitter as the engine will, u1e_names_gate.py proves the names held, and every check maps names through u1e_names.table(ir).
  • find_or_add_module_script finds by NAME: two writers asking for "EventGenerator" share one module, and a parent has ONE location event. Register every generator a parent has (_parent_gens) before naming a new one.
  • ReceiveLocationEvent's Float 1 -> NormalizedAge apply also writes Age = Float 1 x Lifetime: send 0 there.
  • A dying particle moves once more before GenerateDeathEvent takes its position: keep it in an update assignment and send it through "Vector to Send as Vector 1 (Position)".
  • A spawn-stage assignment runs before InitializeParticle ("read before being set", and the system runs nothing). An event-spawned particle needs InitializeParticle, or it is born with lifetime 0; it reads Age = DeltaTime / 2 on its first frame.
  • A location generator in an event script fires nothing: route a birth child of a one-point-per-event middle to the grandparent. Use Event Probability does not gate an Every Frame location event.
  • A parent's last tick's events are read twice (the converter's guard kills the stale ones); an event-spawned child's curves apply twice; a particle killed in its first update still fires its generators (gate generation on the lifetime).
  • Deleting an if line can leave its block nested after the previous branch's return, never run and never reported. py unreachable_gate.py (in vfxport/) refuses it. A stand-in dry run counts calls on the EMITTER context (sysctx.add_empty_emitter.return_value), not the system context.
  • A ported child changes its whole family: whole_trace.py --with-parents widens the expected set to the parents the children name.

Frames, textures and capture

  • A polygon's first three corners are not its normal (a concave quad): judge winding by corner ORDER. A material's "Local" space is the particle's own transform for a mesh particle, the primitive's for a sprite.
  • A texture's platform data builds ASYNCHRONOUSLY; a draw before it finishes samples EXACTLY 0, and blueprint_get_size_x/y reads 32 x 32. unreal.AssetCompilingManager, unreal.TextureCompilingManager and UTexture.update_resource do not exist in 5.7's Python; the only reachable flush is unreal.SystemLibrary.execute_console_command(None, "Editor.AsyncAssetCompilationFinishAll"), before EVERY draw. -NoTextureStreaming and never_stream do not help (13 of 13 textures, 2026-09-29).
  • Never use a WHITE texture as a binding's control: Runtime/Engine/Private/Materials/MaterialUniformExpressions.cpp:1396-1401 binds GWhiteTexture for an invalid binding, so success and failure look alike.
  • Unreal reads gamma off the IMAGE, Unity off the importer flag: Editor/UnrealEd/Private/Factories/EditorFactories.cpp:2941 sets bSRGB from LoadedImage.GammaSpace != EGammaSpace::Linear, and a 16-bit source is linear. Texture.srgb cannot fix it; SourceColorSettings.EncodingOverride = TSE_S_RGB can, on 16-bit sources only (on an 8-bit source maxTextureSize downscales it is worse). The member is TSE_S_RGB, not TSE_SRGB.
  • Unreal DISCARDS a BLEND_MASKED pixel below the clip value: a reference compositing opaque charged the material 41.1705 for an instrument gap (the true residual 0.0219).
  • The filmic tonemapper sends display values under about 16 / 255 to 0 (compare faint halos untonemapped), and an isolate photo can leak bursts at time 0 (read its live counts).

Harness and gates

  • A gate's input format is part of the gate: an audit that read one way of setting a switch missed six trial switches. Widen it, then watch it fail.
  • A check that judges a stand-in, or an emitter Unity never emits, fails emitters that are right; a raw-name match against the absent list flags a built twin. Judge by the build's notes, the IR's flags and the file id.
  • A log gate written without the known noise misfires, and a value found anywhere is vacuous ("1.0" is in "-1.0").
  • A queue's FAIL branch acts on the check's verdict: run a new check that guards an automatic restore by hand first.
  • Preflight every headless Unreal launch (effects_tools/u1e_preflight.py), and grep the checks that execute a converter function before giving it a new dependency.
  • PowerShell names are case-insensitive: a loop over $s overwrote $S, and a queue skipped its read and checks yet wrote its done marker. A step whose output is missing prints FAILED.
  • A watchdog sized by a smaller run kills a bigger one: compare the key count built with the keys asked, after every build.

12. The Unity tools: headless, driving an editor, several agents

Who this is for: the porting developer who needs Unity's answers. After it you can pick the tool that gets each answer with no editor, drive an editor someone is working in without disturbing them, and recognise the traps each tool guards against.

A port is held to Unity, so it needs Unity's answers: what a file stores, whether the C# still compiles, whether a test passes, and what the engine actually does at a given frame.

One rule runs through all of it. The Unity editor on your machine belongs to the person working in it, its owner. A tool that can answer without an editor never starts one. A tool that needs an editor waits until the owner is away, and leaves the editor exactly as it found it.

The three ways to work with Unity

way what runs what it can answer what it costs the owner pick it when
No editor Python and .NET reading Unity's files; Unity's own compiler and Mono; NUnit, the .NET test framework Unity's tests are written in what a file stores, what Unity imported, whether the C# compiles, whether a logic test passes, a rule's answer on Unity's own runtime nothing: no window, no focus always first
Driving a live editor an HTTP server inside the owner's editor, and the idle-gated window runner what the running engine does: a probe's measurements, the console, a screenshot, Play the editor itself: a recompile, a probe dropped in and taken out the answer exists only inside Unity, and the owner is away
A second editor instance a full Unity Editor on a clone of the project, on its own port the Unity Test Runner, editor tools, anything the live editor could do, without touching it a second full GUI editor on the owner's desktop, taking focus on every assembly reload the owner has allowed it and its kill switch is off (below)

The order is the order of preference. A question moves down a row only when the row above cannot answer it, and the reason is written down. "The test lives in an Editor/ folder" is not a reason: the headless NUnit runner runs those. "The test opens a scene through AssetDatabase" (the editor's own asset API) is.

No editor: reading Unity's files

Unity serialises scenes, prefabs, materials, ScriptableObjects and .meta files as YAML text. What the inspector shows is what the file stores (serialisation beats the C# initialiser), so the toolkit reads values there and never retypes them.

verb or tool what it reads where it is described
u2ue extract every effect prefab, into one IR file per key Chapter 7
u2ue data one component's or ScriptableObject's serialized values below
u2ue inventory, u2ue uml the game's C#, type by type, and its class model Chapter 5
u2ue shear, u2ue scene scene nodes Unreal cannot place; a scene's import and its fidelity gate (its export runs in a window) Chapter 6
vfxport/yaml_field_gate.py a Unity field a reader neither reads nor excuses, refused by name Chapter 9

u2ue data finds every matching component, expands nested prefab instances with their modifications applied (a value an override changed is the override's), and writes each component's GameObject path, its fileID (the object's id inside its file) and every field as the file stores it; a reference {fileID, guid} (an object in the file that guid names) carries the asset path it names.

py -m u2ue --project <game> data --from <Assets/...prefab> --script <ClassName> --tsv <out.tsv>
py -m u2ue --project <game> data --from <Assets/...unity> --class Light --no-expand

--script matches a MonoBehaviour by its script's guid, never a line number (a re-saved file moves its lines); --class takes a class id (20 Camera, 108 Light) or a YAML type name; --tsv writes one <dotted path> <TAB> <value> row per leaf, which two readers' outputs can be diffed in. The traps a reader must handle (the nested-object fileID, material variants, the blend mode as a number) are in Chapter 6 and Chapter 16.

Unity's imported textures, off Library/Artifacts

Unity samples its imported texture, not the source file. Each import is a SerializedFile (Unity's binary file of serialized objects) under Library/Artifacts/<hh>/<hash>, so "what does Unity actually sample here" needs no window. effects_tools/unity_tex_artifact.py finds the texture's GUID in Library/ArtifactDB (an LMDB key-value database; the GUID's bytes are nibble-swapped), reads the Texture2D fields by value, and refuses unless all agree: the size against the .meta's cap, the image size equal to the format's whole mip chain to the byte, a decoded format (DXT1, DXT5, RGBA32), the mip count, the mip bias. Validate every match against the source: the index's neighbourhood holds other assets' hashes, and 3 of 414 textures first matched a wrong image (measured 2026-10-14: a real match's 4x4 block means sat within about 6 of 255, a wrong image's read 73 to 148).

What the reads show: Unity fills the colour under alpha 0 for alpha-is-transparency textures, averages mips unweighted in linear light, and resamples a non-power-of-two source (512 x 520 became 512 x 512). None of that is in the source PNG.

No editor: the headless C# typecheck

typecheck.py answers the question asked most often, "does the C# still compile", without an editor and with Unity's own answer. Unity has already written its complete compiler command lines to disk, one .rsp per assembly under Library/Bee/artifacts/<dag>/. The tool reuses them with the Roslyn compiler inside that Unity version (Editor/Data/DotNetSdkRoslyn/csc.dll, run by the editor's bundled dotnet), so defines, references and language version are Unity's. It compiles Assembly-CSharp (the assembly Unity builds the game's scripts into), then Assembly-CSharp-Editor (its Editor/ folder scripts) against the fresh runtime assembly.

py typecheck.py                                # both assemblies
py typecheck.py --editor                       # the editor assembly only
py typecheck.py --extra <Probe.cs>             # also compile a file that is not in the project into the editor assembly
py typecheck.py --platform osx                 # with another editor platform's defines (win, osx, linux)
py typecheck.py --as-head [--keep <path>]      # what a fresh checkout of the version-control head compiles
py typecheck.py --model-from-source            # against the engine-free model built from source, not the installed DLLs

Exit 0 is clean, 1 prints the errors, 2 means the check could not run, which it says is not a pass. It proves the code builds, not that it behaves. The traps, each handled in the code:

  • The -out: line is project-relative. A rewrite that misses it lets the compiler write over Unity's own artifact; the tool refuses to compile unless exactly one -out: line was redirected.
  • The editor .rsp references Assembly-CSharp.ref.dll from Unity's last compile; the tool points it at the fresh build, or a changed signature is checked against the stale one.
  • The .rsp is a snapshot. A file created since is appended (else a new file with errors passes, and a new file without errors breaks every file that uses it); a file deleted since is dropped (else CS2001, "Source file could not be found", reads like a broken build). Both are counted.
  • There is one .dag folder per build configuration (the editor's, a development player's). The tool takes the newest holding both command lines: two assemblies from two snapshots compile against two source lists and invent errors.
  • A folder with an .asmdef or an .asmref belongs to another assembly. Without the .asmref rule a package's folder is swept into Assembly-CSharp and produces CS0433 errors (a type that exists in both assemblies) in third-party files. A false failure in innocent code is worse than a missing check: its obvious fix breaks a working project.
  • --as-head reads pending changes from Unity Version Control through its command line, cm (cm status), and compiles each edited file at its head revision, fetched with cm getfile: cm cat re-encodes non-ASCII through the console code page. A precompiled DLL that is not checked in is left out unless --keep names it, as a fresh checkout would.
  • --platform exists because a macOS editor compiles the #else side of every #if UNITY_EDITOR_WIN.
  • It never compiles a player (Unity's build of the game itself, outside the editor), so runtime code calling a member inside #if UNITY_EDITOR passes here and fails in a player build. No tool does that compile yet.

A known gap: typecheck.py has no planted selftest (--selftest-head-has proves only its head listing; it reads no --selftest flag). u2ue cycle, the toolkit's recurring self-check (Chapter 14), runs it under pillar 4 (a pillar is one promise the product makes), so that row proves the project compiled that day, not that the typecheck can fail.

No editor: the headless NUnit runner

Tests that live in a Unity project's Editor/ folder but only exercise data and logic need no editor. headless_nunit/headless_nunit.py runs them under plain NUnit with no Unity process. It exists because the alternative, the Unity Test Runner, starts a full editor (the second instance, below), which can make the owner's machine unusable.

py headless_nunit/headless_nunit.py --test <Assets/.../Editor/SomeTests.cs>
py headless_nunit/headless_nunit.py --test A.cs --test B.cs --filter "FullyQualifiedName~Resolver"
py headless_nunit/headless_nunit.py --test A.cs --typecheck-editor     # also compile the Editor assembly
py headless_nunit/headless_nunit.py --test A.cs --no-compile           # reuse the last compile
py headless_nunit/headless_nunit.py --selftest

--define adds a define and --out names the work directory. Exit 0 means every test passed, 1 a test failed, 2 nothing ran (a filter that matches nothing is a failure, never an empty pass), 3 an environment or compile failure, or a stale build.

How it works

  1. Compile Assembly-CSharp.dll from Unity's own Bee .rsp (the newest Library/Bee/artifacts/*.dag/Assembly-CSharp.rsp) with the bundled Roslyn (Editor/Data/DotNetSdkRoslyn/csc.dll). -out is redirected to the work directory, -refout dropped, every edit guarded, and the rsp's source list reconciled with the files on disk (a brand-new .cs appended, a deleted one dropped). Nothing under Library/ is written. The result is named AC.dll.
  2. Generate a net10 NUnit project that compiles the given test file(s) with UNITY_EDITOR defined, references the fresh AC.dll, and swaps UnityEngine.CoreModule for UnityShimCore/, the shim: a purely managed replacement (Debug, Mathf, Random, Resources, the Vector and Color structs, the Object / Component / MonoBehaviour chain); Resources.Load answers null. It also references the game's own asmdef assemblies at their real implementations in Library/ScriptAssemblies (a Bee .ref.dll holds metadata only and throws when loaded) and the managed plugins under Assets/Plugins.
  3. dotnet test it. HeadlessBoot.cs prints which AC.dll actually ran (its path and MVID, the build id in its metadata), and the tool checks its md5 against step 1's compile, so a stale build can never pass quietly.

Measured on 2026-09-01: a file of 4 tests whose static constructors build the game's whole data tables compiled in 4 s and ran in 15 s, and a mutation run (the code under test deliberately broken, to see whether the tests notice; Chapter 14) failed 3 of 4 with 196 named mismatches.

Expect a minority of a project's editor test files to run as they stand. Of the reference port's 133 (headless_nunit/census_2026-09-07.json), 31 ran clean (340 tests) and 9 more with a helper file passed as a second --test (129 tests); 69 were bound to the editor (66 by their own text, 3 through a file they use) and not run, 22 failed to compile against the shim or failed at run time, and 2 held no tests.

The selftest drives the real runner on the cached compile: a planted passing test must exit 0, a failing one 1, an empty filter 2.

What it cannot run

Anything touching UnityEditor.*, AssetDatabase, real components or scenes, or a UnityEngine member the shim lacks. These fail loudly: TypeLoadException, MissingMethodException or FileNotFoundException, naming the member or the assembly. If the member is pure, add it to UnityShimCore/Shim.cs; if not, the test needs an editor, and the honest report is that it was not run.

  • Copy Unity's declaration kind, not just its name. The code under test calls a property as get_text(), so a shim field of that name throws MissingMethodException (measured on a text asset's text and on Object.name).
  • A CS0103 or CS0246 naming a type is not "cannot run headless". The runner compiles only Assembly-CSharp and the files it is given; pass the file that defines the type as another --test.
  • When a test "needs Unity", usually only its plumbing does. Moved into its own class, the arithmetic of one editor-bound fix ran its 12 tests headless in 1.4 s, and a mutation run failed exactly the 4 relevant ones. Push the logic out, leave the plumbing untested, and say so.

Traps the runner absorbs

  • The bin keeps the SOURCE file name. The reference is AC.dll, so MSBuild copies it as bin/.../AC.dll, not Assembly-CSharp.dll. A mutation run that swaps bin/Assembly-CSharp.dll swaps a file nobody loads, and "passes". Swap bin/AC.dll, and read the LOADED Assembly-CSharp: ... MVID= line every time.
  • NUnit 3.14, not 4. Unity's NUnit is 3.x; NUnit 4 moved Assert.IsNotNull and its relatives to ClassicAssert, so the same test source stops compiling.
  • -out: in the rsp is project-relative, as in the typecheck: the tool rewrites it by line prefix and re-reads the file to verify.
  • A test file changed after the rsp was written is compiled directly (the test project compiles it), but a NEW runtime file only gets in through the reconcile step: watch the "appended" line.
  • Right after a player build, the newest rsp is the player's. The runner takes the newest .dag by time, so it would build AC.dll without UNITY_EDITOR; use --no-compile until the editor compiles again.
  • The Windows console is not UTF-8. Without forcing it, a failure message quoting non-ASCII source died inside the print loop and hid the run's totals.

The game's own plain .NET test project for its engine-free rules (dotnet test <tests project>) needs neither this runner nor Unity. Report what actually ran: "compile-verified headlessly, suite not run" is an honest report.

No editor: Unity's own Mono

A float rule's answer depends on the runtime that compiles and runs it, and Unity's Mono can land one ULP (the smallest step between two floats) from CoreCLR, the runtime of modern .NET. u2ue digest answers a game's rule cases on both with no editor: once for CoreCLR (logic-Headless.txt), once compiled by that Unity version's own csc.exe and run on its mono-bdwgc.exe, the editor's own runtime build (logic-UnityMono.txt).

py -m u2ue --project <game> digest run --entry <Ns.Cases.Build> --cases <Cases.cs>
py -m u2ue --project <game> digest faithful

faithful re-measures that the standalone Mono stands in for the editor: on Unity 6000.3.16f1 (2026-10-16) the digest computed this way equalled the one the editor wrote, 383 rows of 383, including the 35 where Mono and CoreCLR differ. A Unity version with no such measurement is labelled UNMEASURED. Chapter 5, step 7 is the method.

Driving a live editor: the HTTP bridge

When the answer exists only inside a running editor, an agent drives it through an HTTP server inside the editor: the bridge. That server does not ship yet ("What ships, and what does not yet", below), so until it does your project needs its own. What follows is how the reference port's bridge serves: the behaviour the toolkit's tools rely on, and the design to copy.

How it serves

  • It starts with every domain load ([InitializeOnLoad]; a domain load is Unity reloading the scripts' assemblies, as after every compile), and refuses to in a process no person drives: batch mode, an asset-import worker, an editor that is not human-controlled. Those run the same script, and before this rule they bound ports with listeners whose main thread never ticked.
  • A listener on a background thread, bound to both localhost and 127.0.0.1 (the Windows listener treats them separately, and a client may call either), on the first free port of four starting at 7860.
  • The port file. The bound port is written to bridge_port.txt at the project root and under ProjectSettings/; read it every time, since the port moves across restarts. A real stop writes 0, but a domain reload does not: if the reload hangs, a 0 would say "bridge dead" when the truth is "reload stuck".
  • Interruptible accept. The listener waits in 250 ms slices (BeginGetContext, WaitOne(250)), never in one native GetContext(): Mono cannot abort a thread parked in native code, and the old loop froze Unity on "Reloading Domain". Stopping calls Close() as well as Stop(), since only Close() releases the socket.
  • Main-thread dispatch. Unity's API is main-thread only, so requests are queued and EditorApplication.update drains up to four per tick, dropping any older than 10 s (its caller has given up).
  • What answers when the main thread cannot. /ping, /status, /capabilities, /recompile, /play, /stop and /focus are answered on the listener thread from state cached every tick, so they answer during a compile and behind a modal dialog, when an agent needs them most.

/status carries isPlaying, isPaused, isCompiling, compileTick (finished compiles), autoRefreshMode, mainThreadResponsive, mainThreadTickAgeMs, port and hotReload; mainThreadResponsive is true while the last tick is at most 4,000 ms old. /capabilities adds the advertised routes and the edit-mode-only and play-mode-only lists.

A health signal must be stamped after the work it vouches for. On a macOS editor a Windows-only user32.dll call threw on every tick and the dispatch after it never ran, while /status reported a tick stamped above the throw: healthy-looking, and serving nothing. Off Windows, window handles are ABSENT with the reason, and /focus answers 501.

The reference bridge also has a monitor window (its state and last 128 requests) and a menu command that restarts the listener.

The route families

family routes what it does
health /ping, /status, /capabilities alive; editor state; self-description
focus /focus brings the editor's window to the front (a disturbance, below)
compile /recompile a refresh that picks up changed scripts; answers 202, polled through /status
play /play, /stop enter or leave Play; concurrent requests coalesce and the latest intent wins
console /console/entries the Console's own rows, read-only (the console section, below)
events and profiler /events, /events/last, /profiler, /profiler/deep events the game posts; frame time, memory, and Unity's profiler counters averaged over 60 frames
screenshots /screenshot/game-view, /screenshot/scene-view, /sceneview/info, /sceneview/frame a PNG of the Game or Scene view (the Game view's answer carries the file's byte count and md5); the Scene view camera's facts
scenes /scene/save, /scene/reload save the open scenes; reload one from disk on an explicit path (discarding unsaved changes, edit mode only)
prefabs and materials /prefab/measure, /prefab/preview, /prefabs/audit, /materials/remap-urp-lit measure, preview or audit prefabs; re-target a material to URP Lit
imports and shaders /assets/reimport-all, /shaders/check a forced refresh and shader reimport (synchronous and slow); every shader asset's compile state
UI state /ugui/dump, /panel-gallery/* the UI's structured state; a catalogue that spawns any UI panel and captures it alone
tests /test/* in-editor suites run by the bridge and answered as JSON; /test/bridge runs the bridge's own stability tests

Read the picture, and the hash. A screenshot route answering ok with a path proves bytes were written; open the file. Two captures that should differ but share one md5 show a stale frame: with the editor in the background the Game view route returned one md5 twice, 2.5 minutes apart.

Dump the UI's state before iterating on its screenshot. A PNG loses the anchors, the computed rect, the parent canvas, the alpha. /ugui/dump?type=<Panel> first forces the layout to rebuild (LayoutRebuilder.ForceRebuildLayoutImmediate, then Canvas.ForceUpdateCanvases), since a rect read in the frame a layout changed is stale, then returns each panel's rects, parent canvas, alpha and anomalies (alpha 0 while active, Unity's default 100 x 100 never set, and others). The panel catalogue finds every class implementing the game's panel interface by reflection; /panel-gallery/headshot captures one panel alone.

Most routes are the game's own. On the reference bridge the families above are a small part of what it answers; the rest run the game's own suites and set up its levels, cameras, menus and content. Keep the families and bring your game's own.

The advertised list drifts. /capabilities lists routes from a hand-kept array beside the dispatch, so a working route left out of it is invisible to an agent that learns its tools there (read 2026-10-17, the reference bridge answered 13 routes it did not list). A new route can also fail to load when a compile error elsewhere stops the reload, so verify a new route through /capabilities, knowing the advert is a second list. The fix is a dispatch table whose keys are the advert ("What ships", below).

Guards and refusals

A route declares what it needs, and a call that lacks it is refused before any work:

refusal status
the route needs Play and the editor is not playing 400
the route is edit-mode only and the editor is playing 409
the editor is compiling 409, with compileTick
the main thread's last tick is more than 4,000 ms old 503, with mainThreadTickAgeMs

/recompile also refuses while a compile or import is in flight (in_flight) and debounces calls within 2 s (debounced). Without them, an agent retrying faster than Unity could settle scheduled one forced refresh after another, each a domain reload of 13 to 30 s by the bridge's own note, and its wait never converged because it caused the next compile. About 30 ticks after a refresh with no compile, the bridge logs "NO compile started after Refresh": a locked reload, Auto Refresh off, or nothing to compile (a byte-identical file is the last case, and a pass).

Driving a live editor: the measurement window

A probe (the probes, below) must run inside the owner's editor, which is in use. u2ue window runs one probe session from a data file, built so it cannot cost the owner anything; Chapter 8 gives the protocol step by step.

py -m u2ue --project <game> window check <spec.json>    # every refusal judged now; nothing touched
py -m u2ue --project <game> window run <spec.json>      # wait for the owner to be away, then run it
py -m u2ue.verbs.window --selftest                      # the whole flow against a simulated editor

It waits for the owner's quiet and stops at its next step when the owner returns (the gates are under "Never disturb the owner", below). It refuses to start with no bridge, in Play, under another's editor lock, over an existing output, or with a probe that does not compile headless. It removes the probes only while the editor is idle twice 5 s apart (one was once deleted mid-import). It never answers a modal, never enters Play, and never runs the Test Runner.

check exits 0 when the window would start and 2 with its refusals. run writes window-<label>.json into a windows folder under the project's records directory (work.records); PASS exits 0, STOPPED and FAIL 1, a refusal 2. The runner reaches the editor through one small interface, so its selftest swaps in a simulated editor for 11 cases, each of which must leave no probe, trigger or lock. The quiet and presence gates are Windows PowerShell scripts today.

A second editor instance: my_unity.py

Some questions need a real editor that is not the owner's: the Unity Test Runner, an editor tool. my_unity.py gives an agent a full Unity Editor on a clone of the project, on a port the owner's editor never uses, driven through the open-source Unity MCP package's client unity-mcp-cli. That package is an MCP server (MCP: the Model Context Protocol, through which an AI model calls outside tools): it runs inside a Unity editor and lets an AI model call the editor's tools (compared below). my_unity.py is the recipe for doing that safely.

py my_unity.py status                                 # is the clone's server up
py my_unity.py down                                   # close the clone's editor
py my_unity.py test                                   # sync the scripts, run every EditMode test, diff against the baseline
py my_unity.py test --no-sync                         # run against what is already in the clone
py my_unity.py test --method "Fixture.TestName"       # one test
py my_unity.py test --namespace "Some.Namespace"      # one namespace
py my_unity.py up                                     # launch the clone and wait until it serves
py my_unity.py tool <name> --input '{...}'            # one tool of the server
py my_unity.py baseline                               # record a full run as the accepted baseline

An EditMode test is one the Test Runner runs in the editor without entering Play. Exit 0 is verified green, 1 a named problem (a regression, a new failing test, a test that stopped running), 2 an UNKNOWN outcome, 3 blocked by the kill switch.

What it does for the agent

  • Its own port. The clone serves on 58447 and a second clone on 58448, so parallel agents need not queue on one editor; the owner's editor's port (58446 in the reference setup) is never a target.
  • A sync that refuses to destroy work. test mirrors the scripts live to clone (robocopy /MIR, which deletes what only the clone has), but first compares every clone script with its live copy by content and aborts, naming the files, when the clone holds edits live does not. Without that check a sync wiped an agent's work in the clone, and the run reported "no regressions" against code that no longer held it.
  • Assets do not sync into a running editor. Unity owns Assets/ while it runs: an asset copied in was rewritten by the clone from its loaded copy a minute later. Scripts are fine, since they compile from disk; a run that must see a changed asset restarts the clone cold.
  • A tree that stood still. The script tree is hashed before and after; if it moved, the outcome is UNKNOWN. Four runs "on the same tree" reported 31, 29, 23 and 32 failures because other agents were editing the clone mid-run; two runs with the tree frozen shared 33 of 34.
  • Every test named. The server's test tool withholds passing tests unless asked, so a missing name could mean "passed" or "never ran"; the script asks for all (includePassingTests: true). Without it, 1,323 tests came back as 43 rows.
  • A baseline with both sides of the ledger: the total, every test that ran, and the accepted non-passing set. test reports only what the change moved, says which coverage it proved (per name, count only, or UNVERIFIED), and reports a baseline test missing from a complete reply as STOPPED-RUNNING. Names are compared whole (shortened, Apply(Hover,0.7f,"Tex") splits on the dot in 0.7f). A subset run never touches the baseline.
  • A lost reply recovered from the run's own file. A test call can time out while the run carries on; the script waits for a TestResults.xml written after the run started and parses it once its size holds across a poll (parsed the moment it was fresh, it was caught half-written).
  • The clone's own startup modals closed, by name only. A native modal blocks the main thread, so the server never starts (a migration prompt held a clone over 10 minutes). Only the clone's own popups whose titles name a known blocking dialog are closed: closing every owned titled popup also closed a torn-off Scene view.
  • The client's traps absorbed (listed under the MCP server, below): a 20-minute call timeout, a busy runner retried every 30 s up to 20 times, and UTF-8 output forced (its box-drawing characters on a cp1252 console produced no output at all, which read as a hang).

What it costs, and the kill switch

The cost is not CPU. The clone is a full GUI editor on the owner's desktop:

  • It takes window focus on every assembly reload, and a full run reloads many times. Its modal dialogs take system focus too: a startup prompt raised three times in one session broke /focus on the owner's editor each time.
  • Measured on the reference project (2026-08-29 and 2026-09-01): a full EditMode run took about 7.5 minutes, a --method run about 8 s, a --namespace run about 12 s, and a cold clone sat at about 15 s of CPU per 5 s of wall time for about 30 minutes.
  • Left on top of the owner's editor holding a modal, it kept that editor in the background, and the owner's editor did not rebuild its scripts for a day; closing the dialog and minimising the clone made it compile within seconds.

So the second instance is opt-in, behind a kill switch, added after an agent looped a test command that launched the clone on every run until the owner could not use the machine. While .opus-tools/.UNITY_TESTS_DISABLED exists, my_unity.py exits 3 for test, up, tool and baseline, printing the file's reason; status and down still work, because they are how an agent inspects and cleans up. Only the owner removes the file. A message does not stop a loop that is already running; refusing to start does. Launching the editor another way (the MCP client directly, its test tool, Unity.exe) is the same act, not a workaround: an agent that cannot proceed without an editor reports itself blocked and asks.

When the owner allows a run, one approval covers one run, a subset's approval is not a full run's, runs are never stacked or put in an unattended retry loop, and my_unity.py down ends every session.

Several agents at once

One driver per editor

An editor is single-tenant. The bridge serialises each route call on the main thread, but a logical operation is several calls - hide every panel, show one, capture it - and nothing makes the sequence atomic: two agents interleave and each captures the other's state. The bridge protects single calls (concurrent /play and /stop coalesce to the latest intent; /recompile debounces), never sequences. So:

  • One Unity-driver agent per editor. Every route call, recompile, Play and window for that editor goes through it.
  • Every other agent works headless (the code index, version control, requirements, the readers, the typecheck, the headless tests) and asks the driver for any editor action.
  • Never two agents on one editor. An agent that needs its own editor gets the second instance, when the owner allows it, or waits.
  • Read-only diagnosis is always safe: the body of /capabilities, the tail of the editor log, unity_recovery.py --check. Before mutating, check for another live session: several sessions have been found on one editor at once.

The editor lock, .opus-tools/.locks/unity-editor.lock, is a text file naming who holds the editor, why, and since when. The window runner refuses while anyone else holds it and holds it for its whole life; any tool that changes editor state should do the same.

An MCP server on a default port is reachable by every default-configured client. One was found running inside an owner's live editor after a full EditMode session had run there and discarded an unsaved scene (the server the prime suspect, not proven). Never call the test tool or the MCP client without an explicit port.

The mail channel

Agents coordinate through files, with no server: agent_mail.py appends to .agent-mail/messages.jsonl and keeps read state in .agent-mail/read.json. Each agent keeps one stable name (--from / --as, or AGENT_MAIL_NAME); AGENT_MAIL_ROOT points every command at a sandbox.

py agent_mail.py send --from <me> --to <them> --subject S --body TEXT       # body "-" reads stdin
py agent_mail.py inbox --as <me>
py agent_mail.py ask --from <me> --to unity-driver --subject S --body TEXT --timeout 60
py agent_mail.py broadcast --from <me> --to "*" --subject S --body TEXT
py agent_mail.py watch --as <me> --seconds 60

read, mark-read, thread and agents complete the set. ask exits 0 when a reply to its message lands and 3 on timeout. bot is an auto-responder for tests (modes ack, echo, silent, error).

tool what it does
agent_super.py watch a long-lived inbox tail with a subject filter, so a supervisor sees only what matters (--as supervisor --filter HELP)
agent_super.py fanout sends each task of a JSON list to its worker, collects every reply within a timeout, and reports each reply's latency and the tasks that got none
agent_boot.py up --config harness.json starts a worker pool as background processes; status, down, logs --name; PIDs in .opus-tools/.harness-state.json, logs in .opus-tools/.harness-logs/
agent_harness.py the channel's own tests, each scenario in its own sandbox with an explicit pass criterion (from send and inbox to concurrent writes with no loss). Exit 0 only when all pass; --only T4,T5 runs a subset

The pattern that encodes the driver rule: one worker named unity-driver beside the analysis workers, and a supervisor that sends only editor tasks to it through agent_super.py fanout.

Never disturb the owner

Is the owner at the machine?

Windows' GetLastInputInfo cannot be trusted to say. Measured on the reference machine (2026-10-03): its idle time read 0.00 to 0.02 s on every sample while the cursor sat on one pixel and nothing was pressed, resetting about every 16 ms as if something injected zero-move input. Presence is read from the inputs themselves: the cursor (GetCursorPos) and every key and button (GetAsyncKeyState over 1 to 254). lane/wait_quiet.ps1 samples them every 250 ms and returns only after 600 s with the cursor unmoved and nothing pressed, printing QUIET; lane/wait_presence.ps1 samples them every second (its default) and prints one PRESENT line when either changes. A gate that never says QUIET has refused.

Focus

  • Entering Play focuses the Game view, and the owner's keystrokes land in the game (input that was not a capture's once played a turn during one). Before any Play: the owner away, the editor lock held, one short session, and a capture that checks isPlaying and a sane screen size or is discarded.
  • /focus is a disturbance. Windows does not let a background process take the foreground, so the bridge briefly attaches its input to the foreground thread's (AttachThreadInput) and reports ok: false with the reason when that fails. Restoring the window unconditionally un-maximises a maximised one (an owner's editor was found shrunk to 890 x 474). Taking focus is not permission to resize.
  • Whether a background editor compiles has been measured both ways: one behind another window did not rebuild until it came forward, and another time /recompile compiled and reloaded a background editor twice, in 30 to 60 s each. Assume neither: the editor assembly in Library/ScriptAssemblies being newer than the edited source is the only honest compile signal.

Work queued on delayCall never runs in the background

EditorApplication.delayCall does not fire while the editor is unfocused; EditorApplication.update keeps ticking. Measured twice (2026-08-28 and 2026-10-07): /recompile and /play scheduled through delayCall never ran in the background, so the bridge acts on them from its update tick; and an import watcher's delayCall body ran zero times over six imports while /status showed a tick every 39 ms. Anything that must run after an import or a route call goes on a pending list drained by the next update tick, each step in its own try / catch so one failure is red and the rest still run. delayCall is safe only as a redundant second path.

Recompile, then Play

Unity defers an assembly reload while in Play, so a /play sent too soon after /recompile runs the old assembly for minutes while /status says isPlaying: true, isCompiling: true. The symptom: an A/B run's "after" reproduces the "before" numbers exactly, because it measured the pre-edit build. The safe order:

  1. Edit, then /recompile: it answers 202 with the current compileTick.
  2. Poll /status until isCompiling is false on three consecutive polls, then wait about 20 s: the compile and its reload are done.
  3. Check that the editor assembly in Library/ScriptAssemblies is newer than the edited .cs: the running code is the edit.
  4. Then /play. If isCompiling stays true through Play, or the run reproduces the old numbers exactly, it measured the old build.

A native modal dialog runs its own message pump on the main thread. The dialog stays clickable, but EditorApplication.update never ticks: windows stop repainting (an unrelated tool window seemed to "disappear"), queued routes never run, a probe never sees its trigger. The listener thread keeps answering, so an HTTP 200 proves nothing; the honest signal is mainThreadResponsive: false with mainThreadTickAgeMs climbing.

  • Enumerate the windows and their owning processes before calling an editor hung. An editor taken for hung was healthy: a second editor's modal sat on top of it. The editor log (%LOCALAPPDATA%/Unity/Editor/Editor.log) is shared by every editor on the machine; a window enumeration says which is which. Read titles with InternalGetWindowText: GetWindowTextW blocks while Unity's main thread is busy.
  • After an unclean exit Unity asks to recover its scene backups and does not start until someone answers: the title "Recovering Scene Backups", about 72 MB and no CPU, where a real start passes 900 MB within seconds. The dialog is the owner's: answer it only when the owner has said to, otherwise say in one line what the editor waits on.

Recovery: unity_recovery.py and bridge_wake.py

py unity_recovery.py --check       # read-only diagnosis
py unity_recovery.py --wait        # poll until the bridge answers (--timeout, default 300 s)
py unity_recovery.py --auto        # diagnose, then apply the matching recovery and wait
py unity_recovery.py --kill        # end every Unity.exe
py unity_recovery.py --restart     # kill, then relaunch

--check reads the Unity.exe processes, the port file with a TCP connect and a GET of /capabilities, and the editor log's age and last reload lines, and names the first state that matches:

state what it saw recovery
crashed no editor process, no bridge relaunch
hung_in_reload an editor, no bridge, a reload begun and not finished kill and relaunch
hung_unresponsive an editor, no bridge, the log untouched for over 90 s kill and relaunch
bridge_down an editor, a fresh log, no bridge (between a stop and a start) wait, then relaunch if it does not recover
ok an editor and a bridge answering 200 none

A relaunch starts the version in ProjectSettings/ProjectVersion.txt directly with -no-safe-mode (a Hub already running sent the project to its picker instead) and dismisses the post-crash safe-mode prompt. Exit 0 is healthy or recovered, 1 anything else. The traps, each measured:

  • Unity 6 never logs "End MonoManager ReloadAssembly": 55 begins, 0 ends and 55 "Domain Reload Profiling" lines (measured 2026-10-01). The tool counts the Profiling line as the end; on the End marker alone, a bridge hiccup on a healthy idle editor reads as hung_in_reload and the editor is killed.
  • A fresh log does not prove a live main thread: a hot-reload watcher process kept writing while the main thread sat dead, and an 18-minute hang read as bridge_down. The tool filters watcher lines.
  • --check is blind to a modal: it reads the HTTP status of /capabilities, never the body. Read mainThreadResponsive yourself.
  • --kill, --restart and --auto act on every Unity.exe, found by image name: with the owner's editor and a clone open, a kill ends both. Never run them near the owner's editor without the owner's word.
  • After --auto kills an editor, "the bridge did not come up within 180 s" usually means the recovery dialog is waiting.

bridge_wake.py calls /focus, then polls /status until mainThreadResponsive (exit 0; --timeout, default 30 s; --port; --quiet); --recover runs unity_recovery.py --auto on a timeout and polls again. Exit 1 is a usage or port-file error, 3 a timeout. Since it starts with /focus, it is for an editor the agent owns, or for when the owner is away.

The console as the headless test

A compiler proves the code builds; the console is the cheap thing that proves it ran. On the reference port three faults in one session passed every other instrument (the typecheck clean, 4,104 of 4,104 .NET tests green, a player compile with 0 errors) and were obvious in the console within one frame: a tool opened a scene with broken prefabs (79 errors blamed on the tool's own file, which read from outside as "it does not compile"); a row of the level's grid lost its tiles and an exception emptied the board; a render pass bound the back buffer's depth (4,020 errors, nothing rendered).

So console_check.py is a gate, not a glance:

py console_check.py --reset                          # mark everything now in the console as seen
<the action>
py console_check.py --label "what I just did"        # exit 1 = NEW errors appeared
  • One HTTP call to /console/entries, which reads the Console itself (UnityEditor.LogEntries, by reflection), not the editor log: the Console retires rows when an asset reimports cleanly or a reload succeeds, and knows each row's severity. The route is read-only (it never clears the Console or changes its filter, and reports the active filter), and it fails loudly when the internal API changes shape, because a silent empty list would read as "no errors".
  • A watermark in .opus-tools/.console-watermark.json makes each call report only what is NEW; the backlog is never re-reported.
  • Identical rows collapse with a count. A row's identity is its kind, file and message with every number masked, so an error repeated 4,020 times with a changing frame number prints as one row.
  • Noise is counted apart, never hidden. Unity's search-index and LMDB lock messages, Unity packages' own messages, asset unloading and licensing lines are totalled separately: they can neither mask a regression nor trip the exit code.
  • --all ignores the watermark, --quiet prints only news, --label names the action. Exit 0 is clean, 1 new errors (new warnings are reported but do not fail), 2 the bridge unreachable or the route refused, which is not a pass, 4 a read the gate refuses to judge: the Console window hides errors (its Error toggle is off), or the route listed fewer rows than the window shows.
  • --selftest plants rows through the gate's own function (a seen backlog, a new error, 4,020 per-frame errors, noise, a warning, the same console twice), each judged as above, plays a 251-row Console through the gate's whole run (below), and never touches the real watermark or the bridge.

New errors mean stop and fix. When the change touches rendering, pair the check with a short Play: many faults exist only in a frame.

Every row, or no verdict (found 2026-10-17 by reading both sources, fixed 2026-10-21). The route lists the window's rows from the first and stops at max (default 200), while a new error is appended at the end. The gate used to ask for limit, a parameter the route never read: on a console holding more than 200 rows, a new error after the 200th was counted in the totals line the gate prints but was not in the list, so it was never reported as new and the exit code stayed 0. On the reference port the Console held 2,303 rows when it was measured, and the gate had been judging the first 200. The gate now sends max at the largest value the route parses (2,147,483,647; the route silently replaces anything past it with 200), so every row comes back in the one call, and it refuses (exit 4) any listing shorter than the row count the route reports for the window, so no cap can read as clean again. --selftest plays that console through the gate's whole run against a model of the route: 250 rows already seen and a new error at row 251 is reported (exit 1) when the gate asks its way, and refused, the watermark untouched, when the route lists only its first 200 rows or stops one row short.

Compared with the open-source Unity MCP server

The open-source Unity MCP server package (measured at version 0.87.0) exposes the editor to AI agents as tools, the Unity Test Runner included (its tests-run tool). The second instance (my_unity.py) drives it on a clone. Its client needs no MCP wiring: unity-mcp-cli run-tool <name> --input '{...}' and run-system-tool call a tool directly, unity-mcp-cli status proves the server is up, and unity-mcp-cli install-plugin --path <project> installs it (a package resolve and a domain reload, so never into an editor in use). Its narrow test filters, testMethod and testNamespace, work (the timings above).

What was measured against it

  • testClass does not filter: it answers "No tests found matching class ..." for a bare and a fully qualified class name.
  • The client's default timeout is 60 s, shorter than a real test run, so the first call reports a bogus failure.
  • A timed-out call leaves the run in flight, and the retry answers 500, "another test run is already in progress". Wait it out; do not relaunch Unity over it.
  • Every call needs an open editor, because the server lives in one: the owner's, or a second instance with the costs above. Its connection was seen to drop while the editor was in the background (null replies, "not connected").
  • A configured server that is not running still lists its tool names: a project carried the tool descriptions (86 at that version) with no package installed, advertising a toolbox no server could serve. "Listed" never means "available".
  • On a default port it is reachable by any default-configured client (the finding above).

What ships, and what does not yet

Ships in the toolkit's tree today: every toolkit verb and tool this chapter names. The bridge and the editor scripts behind its routes do not. Several of the tools still default to the reference project's folder instead of reading it from the project file; moving each one is the "No absolute paths" item of Appendix B.

The bridge does NOT ship yet. It lives inside the reference project, with the game's routes in the same file as the server. Until its generic core is in the package, a window, the console gate and the recovery tools need a bridge in your project, and a new project has none (Chapter 22 lists "a Unity measurement in another studio's editor without the reference port's bridge" as OPEN). Write yours to the behaviour above, with your game's routes registered in a table whose keys /capabilities lists, so the advert cannot drift from the dispatch.

What the package's own tools call on that server today, read from their source:

tool what it calls
u2ue window bridge_port.txt at the project root; /status (isPlaying, isCompiling); /recompile
console_check.py /console/entries, answering ok, totals (errors, warnings, logs) and entries (each kind, file, message)
unity_recovery.py /capabilities answering 200
bridge_wake.py /focus; /status (mainThreadResponsive, mainThreadTickAgeMs)

Appendix B carries the related item: the probes and the window driver as the package's Editor assembly, triggered by a file, with no dependency on the reference port's bridge.

The probes

A probe is an editor script that sets up one Unity behaviour, steps it, and writes what it observed to a fact file; its judge states the rule a port relies on and reads it off the facts or refuses it with the numbers (Chapter 8: the judge is written and planted first). Probes live in the toolkit, not the game: vfxport/unity_probe/ holds the probes, the shared placement helper ProbeSpawn.cs, and their *_judge.py and *_check.py files. A probe is copied into the project's editor folder (unity.probe_dir) for one window and taken out again.

The shape of a probe

  • Triggered by a file. An [InitializeOnLoadMethod] hooks EditorApplication.update (never delayCall) to poll for its trigger in the conformance part (the toolkit's folder of measured Unity rules, Chapter 3). The generic case probe skips every tick while the editor plays or compiles; when its trigger appears it deletes it, reads the lines the window wrote (a spec and a record name), and runs. Nothing has to click.
  • Edit mode, in a preview scene. The case probe and the photo probe place their systems in a preview scene (EditorSceneManager.NewPreviewScene), so the owner's active scene is never touched; its dirty flag is recorded before and after.
  • One record out, never over another. The case probe refuses to write a record that exists (and the runner refuses to start any probe whose output exists); a probe reports an error inside its record rather than throwing.
  • Compiled headless before it enters the project (typecheck.py --editor --extra <probe.cs>).
  • Real prefabs are placed only through ProbeSpawn, which names the placement measured (the game's effect spawn, its projectile spawn, or the prefab as authored). One probe that placed prefabs its own way dropped the root's authored rotation and made 36 reference frames wrong. vfxport/probe_spawn_gate.py refuses a probe that sets an instantiated prefab's transform itself, and the runner drops ProbeSpawn.cs in with any probe that calls it.
  • A query that can crash Unity is guarded. ParticleSystem.Particle.GetMeshIndex on a renderer without meshes kills the editor in native code, which no managed try / catch sees (Chapter 16).

A probe case is data

Hand-written probes grow: ColorSizeFactsProbe.cs reached 5,915 lines of hand-written cases. ParticleCaseProbe.cs is one generic probe for every particle question, the question given as data, and u2ue/probecase.py writes that data:

  • ProbeCase.prefab(name, path, times, spawn=...): a real prefab placed by the game's spawn (effect, projectile, authored), listing the systems the game never starts so they are cleared after every step.
  • ProbeCase.synthetic(name, modules, times): one system whose module properties are set by name ({"main": {...}, "emission": {...}}): a rule question with no new C#.
  • Every case pins the random seed on every system (two runs are identical), lists its read times and per-particle fields, and caps the particles written (the count is always whole).
  • Restart or step. Without a step, each time is simulated from a restart; with one, the probe restarts once and steps the way the game does, so the times must ascend. The restart read is blind to a sub-emitter of a sub-emitter: it drew 0 of 284, and a read stepped at the game's own 1/60 s drew 12 of 12 (Chapter 9).
  • CaseRun(name, cases, why) writes <name>-cases.json in the conformance part and the window spec <name>.json under the lane part's windows/, refusing to replace either; the window writes <name>-unity.json.
py -m u2ue.probecase --selftest      # a prefab case, a synthetic case, bad cases and runs refused, nothing replaced

u2ue conform cases builds a run of every IR key this way (Chapter 9). A rule question needs no new probe file: the simulation-speed rule was measured from 24 synthetic cases (simspeed-cases.json).

13. The Unreal tools: headless runs, the host, publishing

Who this is for: the porting developer who runs Unreal. After it you can launch Unreal headless safely, make the game's own Unreal project, publish its managed C# (the .NET code UnrealSharp runs) and prove the build that runs is yours.

Every Unreal step of a port runs the same way: headless, from native PowerShell, one engine at a time, through one runner that refuses an unsafe launch, and judged by what the run wrote, never by its exit code. This chapter is each Unreal-side tool, why it is built that way, and the traps it catches; Chapter 16's "Unreal runs" entries are the short form, by symptom.

tool what it is
scene_tools/ue_headless.ps1 the one place an Unreal executable is named: six launch rules, a watchdog, the argument builders
scene_tools/ue_headless_selftest.ps1 the six rules made to refuse
u2ue/ue_py.ps1, u2ue/ue_game.ps1 one headless Python script (scene import, readback); one headless game start (host run)
effects_tools/u1e_py.ps1, effects_tools/fx17_build.ps1 one effect instrument; one chunk of effect keys built (build, read, photo, trial)
u2ue/verbs/_ue.py what the Unreal verbs share: the host guard, the PATH check, the runner, the build record
u2ue/hostproject.py, u2ue/verbs/host.py, u2ue/templates/unreal the game's own Unreal project, made from the toolkit's template
u2ue/runtime the engine-free libraries the port links

Headless Unreal runs

Native PowerShell, never a shell that rewrote the PATH

UnrealSharp, the plugin that runs C# in Unreal, finds the .NET SDK by scanning PATH for an existing directory entry that contains Program Files\dotnet\, trailing backslash included (read from the plugin's source). Native PowerShell's PATH has it. A PowerShell started from Git Bash, even indirectly (Bash runs Python, Python runs pwsh), inherits a PATH that MSYS (Git Bash's Unix layer) converted, where the entry reads /c/Program Files/dotnet or has lost its backslash. UnrealSharp then reports the SDK missing and raises a modal dialog, which under -unattended (the flag for a run with no one there to answer a prompt; rule R2, below) is answered and raised again forever: the run never ends and its log never stops growing. Measured on the reference port: one such run reached 14.5 GB resident and a 3 GB log before anyone looked (2026-09-29); another raised 265 497 dialogs in a 634 MB log and never did its work (2026-10-02).

So it is checked twice before anything starts: every verb that starts Unreal asks native_path_ok (u2ue/verbs/_ue.py) and refuses with "run from native PowerShell", and the runner's rule R6 refuses the launch, asking UnrealSharp's own question, backslash included. Open a PowerShell window and type the facade command there.

One headless Unreal at a time

The Unreal host - the machine's capacity to run Unreal, as Chapter 2's host_busy row names it, and not the host project of u2ue host below - is one machine-wide resource: two engines contend for memory, the derived-data cache (where Unreal keeps what it derives from assets, such as compiled shaders) and the project's packages (its asset files), and an open editor locks packages another process needs to save (below). So every verb that starts Unreal asks the adapter's host_busy and refuses, naming what holds the host, instead of waiting:

  • the default adapter (unity_project) answers busy while any process whose name starts with UnrealEditor runs - an editor you have open counts;
  • a game adapter may add its own build queues (Chapter 18).

build, read and photo exit 1 on that refusal, host and scene exit 2. build, read, photo and scene print the host's state with --dry, and run nothing. fx17_build.ps1 also refuses on its own (exit 9 while any UnrealEditor runs), so a tool run by hand keeps the guard. The verbs start Unreal below normal priority, so the person using the machine keeps it.

The runner and its six rules

scene_tools/ue_headless.ps1 is dot-sourced by every launcher (loaded into the launcher's own scope, . ue_headless.ps1), and every launch goes through its Invoke-UeHeadless, which first calls Assert-UeHeadless on the exact argument list. Each rule is a throw that names itself:

rule refuses measured or read
R1 EXE any executable but UnrealEditor-Cmd.exe, or one not on disk the GUI editor puts windows on the desktop
R2 UNATTENDED a launch without -unattended read from the engine source: it changes how a prompt acts, not whether a window is made
R3 OFFSCREEN a launch without -RenderOffScreen 2026-09-28: an -unattended Python run put two visible windows on the desktop, one the "Executing Python Script..." notification; with -RenderOffScreen, none, and a byte-identical answer. The engine then creates its null platform application: there is no OS window to draw into
R4 ABSLOG a launch without -ABSLOG=<file> a run writes its own log, never Saved/Logs, which an open editor also writes
R5 NO GUI PY -ExecutePythonScript together with -game
R6 DOTNET a PATH with no existing entry containing Program Files\dotnet\ above

The watchdog. A plain wait cannot notice a runaway, so the runner polls every 1.5 s and kills the run with a named reason at its time cap ($script:UeHeadlessMaxSeconds, 1800 s unless the launcher sets one: ue_game.ps1 900, ue_py.ps1 3600) or when the log passes $script:UeHeadlessMaxLogMB (600 MB) - almost always one modal or one error repeated: read the log's last lines. A capped run fails; it never passes. ue_game.ps1, ue_py.ps1 and u1e_py.ps1 end with one line, exit=<code> seconds=<s> logMB=<mb> killed=<reason> log=<path>; a clean host run prints exit=0 seconds=38 logMB=0 killed= log=<work>/host/host-run.log.

The argument builders. New-UePythonArgs makes an editor Python run (-ExecutePythonScript=<script> -unattended -nosplash -stdout -DeterministicAudio -nocef -RenderOffScreen -AllowCommandletRendering -nosourcecontrol -ABSLOG=<log>); New-UeGameArgs a game run. The command line a host run logs, its log path shortened:

/Engine/Maps/Entry -game -RenderOffScreen -unattended -nosplash -stdout -DeterministicAudio
  -ini:Engine:[Audio]:UnfocusedVolumeMultiplier=1.0 -ResX=1280 -ResY=720 -ForceRes -ABSLOG=<work>/host/host-run.log -ExecCmds=quit

-nocef keeps the editor's embedded Chromium unloaded: an effect build crashed 45 s in with an access violation whose every frame was in that library, which loads because -RenderOffScreen still lets the engine render (2026-10-09).

The gate, not in the package yet. The reference port runs a gate beside the runner, and its folders are still that port's, so it does not ship. Write the same one over your own tooling: refuse any file that names an Unreal executable by path outside the runner (except, by name and with its reason, a probe whose job is to measure the window), any launchable reference to UnrealEditor.exe, a file naming an executable without both -unattended and -RenderOffScreen, and a runner that has lost a rule id (exit 0 clean, 1 refused with file and line, 2 could not run). A launcher that named the executable itself would route around every rule above; the gate makes that a failure.

The selftest.

py -m u2ue --project <game> tool ue_headless_selftest.ps1

Nothing launches: Assert-UeHeadless reads only its arguments and the PATH. A clean launch must pass, and R1 to R6 must each throw its own rule (R6 on a Git Bash PATH); each case sets its own PATH, so the result does not depend on the shell that started it.

Audio: no speakers, and no silent mix

A headless game run opens the machine's real audio device unless told otherwise. Measured on the reference port (2026-10-05): a run's sounds played into the headset of the person working at the machine, and a recording of the master submix (the mixer's final output) caught 0.77 s of a 23 s run. -DeterministicAudio loads the non-realtime renderer: each tick renders its own delta, nothing reaches a speaker, a recording follows the game clock. The second trap is inside the mixer: the engine's BaseEngine.ini sets [Audio] UnfocusedVolumeMultiplier=0.0, a headless run is never focused, so it mixes at volume 0 (the port's voices captured at a peak of 0.000000). -ini:Engine:[Audio]:UnfocusedVolumeMultiplier=1.0 fixes it. A third: the engine's own submix recording stops when a silent submix disables itself, so the toolkit's audio plugin captures through a listener that keeps it rendering (below). Add -UseFixedTimeStep -FPS=60 when a capture's timeline must follow the game clock, and leave -DeterministicAudio out of an attended run. A silent run's log says Using Audio Hardware Device Non-realtime Renderer.

Detached launches and the shell's timeout

A shell tool - an agent's, a CI runner's - usually has a timeout, and stopping a task stops its whole process tree. Measured on the reference port (2026-10-06): an effect build of about 70 minutes, run under a 60-minute tool limit, was stopped at 60 minutes with its UnrealEditor-Cmd child, its record never finalised and its resave (each built system saved again in a fresh process; "Built, compiled, simulating", below) never run. The runner's watchdog was never the limit; the tool's timeout was. So:

  • Compare the two limits before any long launch, and give the shell tool the larger one.
  • Cut long work into chunks that fit. The effect build builds a chunk of keys per run (fx17_build.ps1 -MaxSeconds, 6600 s by default) and keeps each chunk's record. It keeps a key's previous system aside until the new one is saved, and puts back any that a killed run never replaced, so no key is left with no asset.
  • Check that a run finished. A build killed by its own watchdog can still look finished (58 of 68 keys, the resave then saving the ten stale systems as current, 2026-10-06). Compare the record's key count with the keys asked for; u2ue trial names every key not built and calls the trial PARTIAL.

Two PowerShell traps hide a stage that never ran. Select-Object -First N stops every upstream command once it has N objects: a build piped into Select-Object -First 1 printed its result, exit 0, and the resave after it never ran (2026-10-06). And every uncaptured expression in a function is output, so $rec = Build swallows its log lines; print through Write-Host.

What a headless run cannot prove

A script never moves a mouse: on the reference port every scripted run passed while a click in the attended editor picked nothing. A -game run never stops Play-In-Editor (PIE, the game played inside the editor): an object kept alive past a session crashed the editor on Stop while every headless proof was green ("UnrealSharp traps", below). Attended play stays part of acceptance.

Editor scripting limits

The converter and the effect instruments are Python scripts run inside the editor (UnrealEditor-Cmd <project> -ExecutePythonScript=<script>, through the runner). Four limits shape all of them, each with its fix in Chapter 11's traps ("Unreal's Python API"): -run=pythonscript asserts without Slate, -ExecutePythonScript quits when the script returns, the editor world does not tick actors (Niagara simulates only in Simulate, Play-In-Editor or when advanced explicitly), and the CascadeToNiagaraConverter plugin must be enabled or FXConverterUtilitiesLibrary does not exist.

Every instrument writes its answer to a JSON record beside its log, and the verb judges that record.

How the read-back advances a system

effects_tools/u1e_color_size_readback.py (run by u2ue read and a trial's read step) needs no tick loop. For each built system it finishes every pending compile (Editor.AsyncAssetCompilationFinishAll), spawns a fresh component in the editor world (NiagaraFunctionLibrary.spawn_system_at_location, at (0, 0, 100000) unless U1E_RB_XF moves and turns it) and activates it once, the game's path. Then, per frame, it captures the system into a Niagara sim cache (a recording of its particles' attributes) with NiagaraSimCacheFunctionLibrary.capture_niagara_sim_cache_immediate(cache, params, component, True, dt) - the True advances the simulation by dt (1/60 s, unless U1E_RB_DT names the step Unity's probe took) before the capture - and reads every particle's attributes off the cache: position, velocity, colour, size, age, ids and the converter's own.

Each frame records whether its capture succeeded, because a system can be built and never simulate. Measured on the reference port (2026-10-10): 19 built systems read 0 of 90 frames ("SimCache Error: No valid simulation data") and no check flagged them, because every check judges the emitters that produced data; and a read of 0 frames exited 0 while two judges reported "0 judged" as if they had looked (2026-10-16). So the tool writes a capture summary beside its record, and u2ue read names every system that captured nothing or fewer frames than asked, and exits 1. The record is written one system at a time, because a single json.dump of a 673-key, 181-frame read held 55 GB of a 64 GB machine (2026-10-16); u2ue/readback.py parses it a system at a time.

U1E_RB_SPAWNSCALE is refused by name: fx.NiagaraGlobalSpawnCountScale exists in Unreal 5.7 only as a tooltip string, so setting it was a silent no-op (2026-10-13). Grep for a console variable's registration, never for its name in prose.

Built, compiled, simulating

  • Built: the converter saved the asset and reported no error (the record's BUILT). That says nothing about the Niagara compile, whose status is not reachable from Python.
  • Compiled for a game: finalize() only requests a compile, so run Editor.AsyncAssetCompilationFinishAll before the save. Even then a system built through a conversion context is saved with an EDIT compile, whose id differs from the one any process without an editor on it computes: every fresh process recompiled it on load, and the effect was blank at its first spawn. effects_tools/u1e_resave.py loads and saves each built system again in a fresh process, where the save waits for the non-edit compile, and reports one that still needs a compile after it. u2ue build runs it on what it built.
  • Simulating: only a read-back proves it; effects_tools/u1e_simulates_check.py is the gate.

Other measured limits of editor Python

Chapter 11's traps give four more with their fixes: a texture drawn before its platform data is built, unreal.Rotator's positional order, set_parameter's false on a failed write, and a conversion context alive at exit. The rest:

  • Failure by return value is general. LevelEditorSubsystem.new_level returns false when the map exists, and does not raise. Check every return.
  • An open editor locks existing packages. Re-saving an existing Niagara system returned false and a map could not be opened for writing, while a NEW package saved fine (2026-09-29). Re-test such a constraint per operation: the managed publish, assumed blocked by the same lock, ran with the editor open (below).
  • A preflight before the engine. u1e_py.ps1 runs effects_tools/u1e_preflight.py on the script and its local imports: a syntax error or an undefined name refuses the run (killed=PREFLIGHT) before minutes of Unreal start. It exists because two faults once reached Unreal that a two-second read finds: a truncated \u escape in a docstring (a syntax error at import, the run dead 30 s in) and a name written before it was bound. It refuses only what is a fault at run time - a syntax error and the undefined-name classes - and nothing about style.
  • Through the facade only. The effect tools refuse to run without the facade's U2UE_* variables, so a tool never runs with another project's paths. By hand: py -m u2ue --project <game> tool <file>.

The launchers

Every verb that starts Unreal checks the host and the PATH first (u2ue/verbs/_ue.py), runs its tool below normal priority with the project's environment, and removes and names every inherited U1E_* and VFXPORT_* variable, so a verb runs the project's defaults, never a switch left over in the shell.

u2ue/ue_py.ps1 (-ScriptPath -UProject -Log -Headless [-MaxSeconds]) runs one Unreal Python script; u2ue/ue_game.ps1 (-UProject -Map -Log -Headless [-MaxSeconds]) one game start with -ExecCmds=quit, since the host's managed module works at StartupModule. Each prints exit=4 with a reason when the runner is missing, or its script (ue_py.ps1) or its project (ue_game.ps1), and passes its environment on to the engine.

The effect build's own tools, which the build, read and photo verbs run:

tool part what it does check
u1e_build.py effects_tools builds one Niagara system per effect key, inside Unreal, through build_niagara.py -
fx17_chunks.py effects_tools cuts the keys into chunks by ESTIMATED build time, most-used effects first; the cost model is measured on a real chunk's per-phase timers -
fx18_chunks.py effects_tools the same for a whole-game rebuild, time-budgeted, so a series that is stopped has built what the game shows most -
u1e_reuse.py effects_tools the build reuses a texture, a material parent or an instance only when nothing it was built from changed -
u1e_reuse_selftest.py effects_tools u1e_reuse.py driven with fakes of Unreal and the material author, outside Unreal yes
u1e_py_introspect.py effects_tools what a few Unreal Python types actually expose - the names READ, not assumed -
u1e_compile_report.py effects_tools WHY a built system does not simulate, in the engine's own words -

The game's own Unreal project: u2ue host

u2ue host makes your game its own .uproject in steps anyone can re-run, the way you would make one by hand: project creation, the plugin install and the host template, touching no other game's project. Here host means the game's host project: the Unreal project whose C# host classes run the model (Chapter 5), not the machine's running Unreal that the verbs guard (above). Each step is the command it runs and the line in its output that proves it.

The project file's block

"unreal": {
  "uproject": "<work>/unreal/<Name>/<Name>.uproject",
  "engine": "<Unreal Engine 5.7 install>",
  "content_root": "/Game/U2UE/<Game>",
  "host": {
    "template": "U2ueHost",
    "plugins": [{"name": "UnrealSharp", "source": "<git url or local clone>", "commit": "<sha>"}],
    "toolkit_plugins": ["U2ueAudio"],
    "sdks_root": "<AutoSDK root, or null>",
    "digest": {"entry": "<Ns>.<Class>.<Method>", "cases": ["<model>/<Model>.Core.Tests/DigestCases.cs"]}
  }
}

Every field is named, never defaulted. The .uproject sits in a folder of its own name, as a new Unreal project does. sdks_root is an AutoSDK root for a machine with no Windows SDK installed (below), null otherwise. digest.entry is a static method returning the digest's text (or an object with a Text() method), and cases the files that define it - the entry and cases u2ue digest runs on CoreCLR and on Unity's Mono (Chapter 5).

The template

u2ue/templates/unreal holds host/U2ueHost - the smallest C++ project a plugin builds in: a .uproject for engine 5.7 with the toolkit's audio plugin, one primary game module that does nothing else, the game and editor targets (BuildSettingsVersion.V6: the installed engine was built with those defaults, and a target that shares its build products may not differ), and a Config/DefaultEngine.ini naming /Engine/Maps/Entry as the game's default map and the editor's startup map - plus Plugins/U2ueAudio and the host classes U2ue.Unreal (both below). Once the game has its own level, point EditorStartupMap at it: a project that opens on an engine template map shows an empty world, and the game cannot be started without hunting for its map.

The steps

py -m u2ue --project <game> host plan prints every step with its command and proof line, host status each step's record (PROVEN, NOT PROVEN, NOT RUN), and host <step> [--dry] runs one.

  1. create - py -m u2ue --project <game> host create writes the project from the template, the template's name replaced by the host's in every path and text file, the block's plugins added to the .uproject. Proves the files are written. Refused when the folder exists: create never overwrites.
  2. install - py -m u2ue --project <game> host install clones each external plugin (git clone --no-checkout, then the pinned commit) and copies each toolkit plugin without build products. Proves each .uplugin on disk and the clone's HEAD at the pin. The source must be a git repository; a local clone downloads nothing.
  3. compile - py -m u2ue --project <game> host compile runs Build.bat <Name>Editor Win64 Development -Project=<uproject> -WaitMutex, with UE_SDKS_ROOT from sdks_root. UnrealSharp's header-tool exporter writes the C# glue (the generated C# bindings to the engine's types) on the way, builds the plugin's managed bindings and generates an empty user solution. Proves Result: Succeeded.
  4. generate - py -m u2ue --project <game> host generate runs UnrealSharp's own command through RunUAT, Unreal's automation tool: RunUAT GenerateProject -ScriptDir=<plugin>/Build/Scripts -Project=<uproject> -ProjectFolder=<root>/Script/Managed<Name> -ProjectName=Managed<Name> -CreateModuleClass -GenerateSolution - what the editor's new C# project dialog runs, read off the plugin - with no editor and no dialog. (Without a managed project, a GUI editor raises a "No C# projects were found" modal at start.) Proves AutomationTool exiting with ExitCode=0 (Success).
  5. wire - py -m u2ue --project <game> host wire adds the model's layers and U2ue.Runtime as project references, the digest cases and three settings to Managed<Name>.csproj, copies the host classes in, and rewrites the module class to answer the digest. Proves each is written (the record counts them). Refused before generate, and a second time.
  6. publish - py -m u2ue --project <game> host publish runs RunUAT BuildUserSolution -ScriptsForProject=<uproject> -Project=<uproject> -OutputPath=<out> to Binaries/Managed, then to Binaries/Managed/net10.0 (steps publish, publish2). Proves, per output, the success line AND a log line ending in Managed<Name> -> <that output>/.
  7. run - py -m u2ue --project <game> host run starts the game once, headless, on the host's GameDefaultMap through u2ue/ue_game.ps1, U2UE_DIGEST_OUT naming <parity.dir>/logic-Unreal.txt. Proves U2UE DIGEST WRITTEN in its log AND the digest written after the run started. Then py -m u2ue --project <game> parity --require Unreal compares the runtimes (Chapter 5).

Each step writes <work.effects>/host/host-<step>.json (command, proof line, seconds, ok, evidence, time) with its log beside it. Exit 0 = the step proved itself, 1 = it ran and did not, 2 = refused before it ran. The Unreal steps (compile, generate, publish, run) are refused while the host is busy or the PATH fails the dotnet check; --dry prints the command (for create, every file) and runs nothing.

Judged by a line, never by an exit code

An exit code has lied, so the host's selftest requires a compile with Result: Succeeded to pass though it exited 1, and one that exited 0 without the line to fail. A success line alone can pass the wrong result too: BuildUserSolution's says nothing about where the assembly went (2026-10-16), so a publish also needs Managed<Name> -> <its output>/ to END a log line - a substring test passes Binaries/Managed/ on a publish to Binaries/Managed/net10.0/, which the selftest caught. The run is judged by its line and by the digest's time, so a digest left by an earlier run is never this run's.

What wire writes, and why

  • EnableSourceControlManagerQueries false: an assembly that depends on git's HEAD changes its MVID on every commit (measured on the reference port), and the MVID is what proves a publish (below).
  • ShouldUnsetParentConfigurationAndPlatform false: without it a Release publish builds references from outside the solution in Debug (measured, the same project).
  • Nullable disable: the host classes are written with nullable annotations off and the generated project turns them on - measured on a fresh host (2026-10-16), 16 nullable warnings and nothing else; 0 after.
  • The module class: at StartupModule, only when U2UE_DIGEST_OUT names a file, it calls the digest entry, writes the text and logs U2UE DIGEST WRITTEN <path> (<n> lines); an editor session that names no file is untouched. Pure C# there needs no world, but nothing that spawns may run there: managed classes are registered later (a measured crash on the reference port).

Measured: the second game's host

What to expect, as a worked example: the second example project's host, made with these steps from nothing on 2026-10-16. From its records:

step seconds evidence
create 0.0 6 files written
install 0.9 UnrealSharp at its pinned commit; the audio plugin copied
compile 254.6 Result: Succeeded
generate 3.1 AutomationTool exiting with ExitCode=0 (Success)
wire 0.0 2 references (the model's one layer, U2ue.Runtime), 1 case file, 4 host classes, the module class
publish 4.8 the success line and Managed<Name> -> .../Binaries/Managed/
publish2 4.4 the success line and Managed<Name> -> .../Binaries/Managed/net10.0/
run 38.6 U2UE DIGEST WRITTEN .../logic-Unreal.txt (642 lines)

About nine minutes from create to the end of run, most of it the C++ compile. parity --require Unreal then exited 0, the Unreal digest byte for byte the headless CoreCLR digest (both runtimes are CoreCLR), and the four host classes had compiled against that host's own UnrealSharp - the template's proof.

py -m u2ue.verbs.host --selftest runs create, install and wire for real in a temporary folder (the real template, a local git plugin with two commits so the pin can be told from the head, the real model's projects) and the Unreal steps through a fake launcher: every judgement and refusal checked, no engine started.

Managed C# in Unreal (UnrealSharp)

UnrealSharp runs the game's model and the host classes as C# inside Unreal. The managed project is Script/Managed<Name>/; the engine loads the published assemblies from Binaries/Managed or Binaries/Managed/net10.0.

Publish to both folders, and prove what runs

Both folders were populated on the reference port and the engine may load either; a publish to one left the other holding the old assemblies (2026-09-29). So every publish runs twice, once per folder. -ScriptsForProject is required, or RunUAT answers "Failed to find command BuildUserSolution", and BuildUserSolution publishes Release (2026-09-30: the published assembly was byte-identical to bin/Release/net10.0 and to no other configuration).

A file's size and time prove nothing about an assembly: both drift between configurations while the code is identical. The witness is the assembly's MVID, from its PE metadata. The reference port's publish gate builds the published configuration fresh and compares, per assembly, the fresh MVID with the published one on each path, requires both paths identical, reads markers from the shipped file itself (an edit never published cannot satisfy it), and checks the run's own witness. Its checks name the reference port's assemblies, so it is the method to copy, and u2ue check does not run it (its selftest launches Unreal).

A matching hash is not evidence that the run ran your build. Measured on the reference port (2026-09-30): an artifact with a new time and a hash equal to its headless reference read exactly like a proof arriving, and came from an attended editor session on the OLD assembly. So the reference port's run writes a manifest when it arms, naming the assembly it is bound to, and the gate proves an artifact only against that. host run applies the smaller form: the digest must be written by this run.

Then prove it runs, not only that it built - host run, or a headless run of the game whose logs match the headless reference byte for byte. Freeze the managed sources from the publish until that proof passes: the MVID check rebuilds the current source, so an edit made during the proving run fails it, correctly, and costs a whole republish.

Automatic hot reload OFF

UnrealSharp's editor watches the managed C# and by default (OnScriptSave) recompiles the moment a file changes. A tool that writes managed code continuously - a model extraction, a code generator - lands a reload in a mid-write instant: the compile fails, and the editor can wedge. Measured on the reference port (2026-09-29): the editor stopped responding and grew from 14.6 GB to 19.9 GB, and the game could not be started. The compile errors were a lie about the code: a type reported missing dozens of times sat in its file, and dotnet build reported 0 errors minutes later. The fix, in the host's Config/DefaultEditorPerProjectUserSettings.ini:

[/Script/UnrealSharpEditor.CSUnrealSharpEditorSettings]
AutomaticHotReloading=Off

Its values are OnScriptSave, OnEditorFocus and Off (the plugin's CSUnrealSharpEditorSettings.h). Tested (2026-09-29): a managed file touched with the editor up, 0 hot reloads in 40 s, the editor responding. Hot reload still works when asked for; a half-written file just cannot take the editor down. With it back on OnScriptSave the rule is absolute: an open editor or a tool writing managed C#, never both. The safe-operation pillar of u2ue cycle reads this file in the project's host and goes red without the line. The host template writes it (u2ue/templates/unreal/host/U2ueHost/Config/DefaultEditorPerProjectUserSettings.ini), and host create refuses to make a host whose Config lacks it (u2ue/hostproject.py; the host selftest plants a template without it). A host made by hand or by an older toolkit may have only DefaultEngine.ini: add the file before its editor is opened while any tool writes managed code.

The editor watches only folders holding a .csproj under Script/ (read from the plugin's source), so a model outside Script/ can be edited and tested with the editor open; on save a file is only parsed, and only a SYNTAX error opens the blocking "C# Hot Reload Error" dialog. Measured with hot reload off (2026-09-30): three managed files written and both publishes run with the editor open logged "Processed dirty file" three times, with no reload, no dialog and no assembly locked. Restart the editor afterwards: its startup builds the solution from the current source, while a manual hot reload would compile against the model loaded at start, and fail. The facade is stricter than the engine: host publish refuses while any Unreal runs, an open editor included.

When an editor wedged: the recovery order

In this order and no other:

  1. Stop the writer and close the editor - the tool's own stop (a trial: py -m u2ue --project <game> trial stop). Proves nothing writes any more: no file under Script/ or the model changes time. The editor must close, since the Unreal steps refuse while it runs.
  2. Test - dotnet test on the model's tests. Proves the code the editor will load is green.
  3. Build - dotnet build Script/Managed<Name>/Managed<Name>.csproj. Proves 0 errors, whatever the wedged editor said.
  4. Republish - py -m u2ue --project <game> host publish. Proves both outputs, each by its own line.
  5. Prove it runs - py -m u2ue --project <game> host run. Proves the digest written by this run.
  6. Restart the editor - only now, on the published build.

UnrealSharp traps

  • USTRUCT fields start zeroed from C#. A USTRUCT is a struct declared to Unreal's reflection. The generated glue is a plain struct, so a C++ default (= -1) is documentation only: built from managed code the field arrives as 0 unless set. On the reference port every UI draw silently changed its colour decode that way (2026-10-02).
  • Glue names. A bool bFoo becomes Foo; when that collides with another property the generator skips one of them, with no error.
  • A missing binding is not proven by a document grep. UnrealSharp.xml lists member names but not return types, and missed whole classes the glue has (347 key names, 0 matches, 2026-09-30). Reflect over copies of the published assemblies (never the live Binaries), or compile a scratch project against the plugin's UnrealSharp.Shared.props - as dotnet build u2ue/templates/unreal/U2ue.Unreal does for the host classes - and prove the check fails on a planted wrong call.
  • The garbage collector sees only engine-side references. A texture kept in a C# dictionary was purged over several frames and the run crashed reading it; IsValid() does not help in that window (2026-10-01). Hold every asset a managed cache keeps across frames through a strong object pointer (the engine's TStrongObjectPtr); a plain C# property on a managed class is invisible to the collector too. Add -ExecCmds="gc.TimeBetweenPurgingPendingKillObjects 0.5" -LogCmds="LogGarbage Verbose" to a headless run to reproduce such faults on demand: a 6-minute intermittent crash became a 32-second deterministic one.
  • Never root a world object. Rooting marks an object so the garbage collector never frees it. A widget rooted for the life of the process crashed the editor when Play-In-Editor stopped (the engine asserts on a session object that survives teardown), 2026-10-01. Root only assets; tear views down in EndPlay.
  • Noise. Property generator is not initialized at shutdown is logged when no managed class declares a [UProperty] (the plugin's source). It matters only before the run's verdict, or once a class has a [UProperty].

UnrealSharp's open issues (read 2026-09-30)

The recent open issues are almost all interop lifetime and marshalling (converting values as they cross between C# and C++) - what you would predict of a managed layer over UObject (Unreal's base object class) memory, and a class of bug a logic-parity test does not see:

  • TArrayReadOnly<T> is a live view into native memory with no lifetime tracking. If the owning native object is garbage collected while managed code holds the view, a later access reads freed memory, which surfaces as a NullReferenceException or as silently wrong data (#740).
  • TextMarshaller.ToNative writes a null TSharedRef for a null managed FText, which corrupts a C#-defined struct's cached defaults and crashes FText::IsEmpty() (#738).
  • An exception escaping an async void method in game code aborts the whole editor.
  • A crash in UCancellableAsyncAction's "Disregard for GC" object class.
  • "Missing dependency / Create Export" errors in a packaged game: a bug on the shipping path.
  • [UFunction] on a C# local function is silently inert.

From the FAQ: UnrealSharp reaches only what is exposed to reflection, the same restriction Blueprint has, so anything else needs C++ written by you; and a UObject class is made with NewObject<T>(), never new T(). The traps a port meets with it, and their fixes, are above, and in Chapter 16.

C++ builds and the SDK root

UnrealBuildTool needs a Windows SDK and a toolchain. A machine with neither fails at once with Platform Win64 is not a valid platform to build (2.5 s on the reference machine, which had no Windows SDK installed at all; 2026-10-03). An AutoSDK folder holds both: set UE_SDKS_ROOT to it in the process that runs Build.bat only - never as a machine or user variable, never by installing an SDK, which needs elevation. host compile sets it from unreal.host.sdks_root. Before reporting an SDK gone, read UnrealBuildTool's backup logs (Log-backup-*.txt, in its folder under the user's local application data) for where the last good build found one.

A project copy of an engine plugin cannot see the engine's Internal headers, which are shown only to modules of their own scope or marked as engine modules (C1083 Cannot open include file, 2026-10-09): add the one Internal folder to the copy's PrivateIncludePaths, checking every include first so one build finds them all.

U2ue.Runtime

u2ue/runtime/U2ue.Runtime targets netstandard2.1 (Unity 2021 and later can load it) and net8.0 (the tests and the hosts), and references nothing engine-shaped. Chapter 5 shows a host using it; what each type stands in for:

type in place of
UnityClock Time.deltaTime (the real step clamped to the project's Maximum Allowed Timestep, times TimeScale), unscaledDeltaTime (unclamped), frameCount, Time.time
Coroutines, Handle, Wait StartCoroutine, StopCoroutine, StopAllCoroutines, WaitForSeconds, WaitForSecondsRealtime
UnityFrame the player loop's order: every Update by execution order, the coroutine phase, every LateUpdate
Platform (ILog, ITextAssets, IKeyValueStore, IFileStore, IJsonCodec<T>, IRandomSource, SeededRandom) Debug.Log, Resources.Load<TextAsset>, PlayerPrefs, the save file, JsonUtility, UnityEngine.Random with its bounds
PlaybackQueue<TEvent>, IPresenter<TEvent> no Unity type: an instant model's events shown one per tick, only while the view is idle
Digest, FloatBits no Unity type: one runtime's answers as u2ue parity reads them, floats as bit patterns
TrailLaw TrailRenderer's points and drawn vertices, as measured

UnityClock's maximum step is a constructor argument, never a constant: it is the project's own (py -m u2ue --project <game> data --from ProjectSettings/TimeManager.asset --class 5). PlaybackQueue refuses a history that shrinks, where the code it was extracted from skipped one silently: a shorter history is a different model or a reset.

dotnet test u2ue/runtime/U2ue.Runtime.Tests runs headless: the clock, coroutine, frame, random, bit, digest and queue rules, the trail law replayed against Unity 6000.3's own play-mode bake (a wrong trail time must fail it). It references only the toolkit, so it builds on any machine. Hold your game to the library the same way the reference port did: step the game's own measured runner and the library through one set of coroutine scripts (a stall past the maximum step, a hit-stop, a waiter, a nested routine, a stop) and require identical logs. The reference port's version of that test references its own presentation project, so the release leaves it out.

U2ue.Ui

u2ue/runtime/U2ue.Ui (net10.0) is the generic part of the UI converter, compiled from the ui/ part's sources with no game reference. It stands in for uGUI and TextMesh Pro on a converted screen, ported line for line from the packages' source and held to Unity's captures, so the Unreal side only loads the textures and submits the frame: UiLayout (the anchor solve, the layout groups, ContentSizeFitter; a grid layout or an aspect-ratio fitter refused), UguiMesh (the vertex stream uGUI hands a CanvasRenderer), UiFrameBuilder (one draw per CanvasRenderer, in Unity's order), UiRaycaster and UiSelectables (the hit order, the colour transitions and the click), and TmpLayout (TextMesh Pro's layout, held to TMP's own output at float32 bit equality on every captured text), among others.

py -m u2ue --project <game> ui test runs U2ue.Ui.Tests, the converter's tests that touch no game type, compiled against the library alone. Measured (2026-10-15): 398 pass alone, and a planted transform defect fails 264. A known gap: no captured screen holds a rotated node, so a planted rotation defect fails none of them.

U2ue.Unreal and U2ueAudio

u2ue/templates/unreal/U2ue.Unreal holds the host classes AU2ueFrameActor, UnrealPointer, UnrealCameraRig and UnrealPlatform.cs (Chapter 5 says what each does). dotnet build u2ue/templates/unreal/U2ue.Unreal compiles them against a real UnrealSharp (U2UE_UNREALSHARP): measured (2026-10-15), 0 warnings, 0 errors, and a planted wrong binding fails with CS1061.

u2ue/templates/unreal/Plugins/U2ueAudio plays the PCM a port renders at run time (Unity's AudioClip.Create and SetData) as 2D voices, the float samples unconverted (UU2ueAudioBridge.PlayPcm), and captures what the mixer rendered into a float WAV through a listener that keeps the main submix rendering. Its self test is the console command u2ue.audio.selftest <wav> (a 440 Hz tone), judged by selftest_judge.py (correlation, pitch and length on every channel; its own --selftest makes a wrong pitch, silence, a truncated tone and noise each fail). selftest_run.ps1 builds the minimal host with the plugin and runs it headless: both were proven on 2026-10-15 (the build in 95 s; the headless -game capture passes the judge on both channels), and pillar 1 of u2ue cycle re-judges that capture.

Build, read, photo

The three Unreal verbs of the effects pipeline (Chapter 7). Each refuses while the host is busy, removes and names inherited U1E_* and VFXPORT_* variables, runs its tools from native PowerShell below normal priority, and is judged by what its run wrote.

u2ue build

py -m u2ue --project <game> build [--keys FILE] [--tag TAG] [--batch N] [--no-resave] [--dry]

The keys are every READ key of the project's resolve that has an IR file, or the list in FILE. Then:

  • effects_tools/fx17_asset_names.py writes the asset-name table (names two different Unity files would share) to records/asset_names.json; a failure stops the build.
  • fx17_build.ps1 builds the keys in one headless run with batched compiles (--batch 12 by default; the cap 450 s a key, at least 2400 s), keeping records/u1e-build-<TAG>.json with each key's verdict. No record is exit 1.
  • Unless --no-resave, the fresh-process resave of only the systems this build made (U1E_RESAVE_ONLY) into <work.effects>/u1e-resave.json - not the build script's own -Resave, which resaves the whole content root (measured on the reference port: about 70 minutes for 672 systems).

Exit 0 only when the build exited 0 and (unless --no-resave) every built system was resaved without error.

u2ue read

py -m u2ue --project <game> read [--tag TAG] [--frames N] [--dry]

Every BUILT system of records/u1e-build-<TAG>.json is read frame by frame (above; 90 frames at 1/60 s by default) into records/rb_<TAG>_<N>.json with its capture summary; a system that captured no frame (a build never resaved reads nothing) or fewer than asked is named, and the verb exits 1. Only the systems and the frame count are passed: a read at another step, moved or repeated, is a trial's (u2ue trial's read step takes dt).

u2ue photo

py -m u2ue --project <game> photo [--tag TAG] [--times 0.1,0.3,0.6,1.0] [--dry]
  • effects_tools/u1e_fx_photo.py draws each BUILT system at each time into photos/unreal/<leaf>_t<ms>.png: spawned in the editor world, advanced by the same sim-cache capture the read uses, photographed by a scene capture that renders only that component from a fixed pose, sky, fog and clouds off. Each system first gets a background frame with nothing in it, which must be black - that is what makes a frame comparable - and warm-up passes come first, because a translucent material still compiling draws nothing.
  • effects_tools/u1e_photo_sheet.py lays each system's Unity frames above its Unreal frames into photos/sheets/<leaf>.png, printing beside each only what the frame is (lit pixel count, the lit area's centre and extent), so an empty or displaced frame is named before anyone opens the sheet.

The run is judged by its capture (u2ue/capture.py), never by the tool's exit: a system with no judgeable frame, or a frame asked for and not written by THIS run, is named, and a system never captured fails the verb. The selftest fakes runs whose exit is 0 every time and requires exit 1 for a system that raised, a frame never written and a run that wrote no result.

The pairing. Unity's frames come from vfxport/unity_probe/EffectPhotoProbe.cs, run in the game's own editor in a measurement window (Chapter 8): the prefab at the origin in a preview scene, every top-level system's automatic random seed off so each draws from its own fixed seed, stepped at 1/60 s (the game's frame) to each time, rendered from (0, 4, -7) looking at (0, 0.5, 0), vertical field of view 50, 512 x 512, on black. u1e_fx_photo.py converts that pose with the port's own axis map. The sheet pairs Unity's float-target frames (photos/unity_hdr) when they exist.

Like for like. Unity's reference camera renders no post-processing, so the Unreal capture leaves the tonemapper off: Unreal's filmic curve sends every display value under about 16/255 to 0, a faint halo's whole outer ring (2026-10-07). The frame must then be encoded as Unity's is: a render target made at run time is linear, so an 8-bit target held linear values as display bytes and every dim pixel read 5 to 13 times too dark. The capture renders to a half-float target, encoded as Unity's target encodes (clamp, sRGB, round).

A photo is one draw (Chapter 11, "Photos are draws; their dates mix"): a frame confirms what the read-back data holds and decides nothing. Open every sheet: a run that says ok has proved only that bytes were written.

A converter route is tried with py -m u2ue --project <game> trial run <spec.json>: the same steps from a data file, built into the trial's own content root with the route's switch on, one Unreal at a time, stoppable between steps (Chapter 7, Chapter 9).

First time on a new machine

Every item names the check that proves it.

  1. The engine is where the runner looks. $script:UeHeadlessExe at the top of scene_tools/ue_headless.ps1 is the one place an executable is named: point it at your install's Engine/Binaries/Win64/UnrealEditor-Cmd.exe. Check: Test-Path on it is True.
  2. Native PowerShell's PATH carries UnrealSharp's marker. In the PowerShell you will run the facade from, $env:PATH -split ';' | Where-Object { $_.Contains('Program Files\dotnet\') -and (Test-Path $_) } prints one entry.
  3. The .NET SDK. dotnet --list-sdks lists a 10.0 SDK: the managed project targets net10.0 (Chapter 3 lists the rest).
  4. The runner refuses each rule. py -m u2ue --project <game> tool ue_headless_selftest.ps1 prints PASS and exits 0.
  5. The Unreal-side selftests pass with no engine. py -m u2ue --project <game> check --only selftests passes; it runs the host, photo, read-back, capture and trial selftests among the rest (Chapter 21 lists them). The host selftest builds its cases from the second example project in u2ue/projects/, so that project's model must be on disk.
  6. The host is free. After extract (Chapter 4), py -m u2ue --project <game> build --dry prints the Unreal host: free.
  7. A Windows SDK, or an AutoSDK. py -m u2ue --project <game> host compile proves Result: Succeeded, or its log says Platform Win64 is not a valid platform to build: then name an AutoSDK root in unreal.host.sdks_root and run it again.
  8. The host, end to end. host plan, then each step from create to run. Check: py -m u2ue --project <game> host status shows every step PROVEN, and py -m u2ue --project <game> parity --require Unreal exits 0.
  9. The host classes match this UnrealSharp. With U2UE_UNREALSHARP set to the host's Plugins/UnrealSharp, dotnet build u2ue/templates/unreal/U2ue.Unreal reports 0 errors.
  10. Hot reload is off before the host's editor is opened while any tool writes managed code. Check: the host's Config/DefaultEditorPerProjectUserSettings.ini holds AutomaticHotReloading=Off under [/Script/UnrealSharpEditor.CSUnrealSharpEditorSettings].
  11. Long launches fit. Check: the shell tool's timeout is at least the launcher's -MaxSeconds.
  12. Runs are silent. Check: a headless game run's log says Using Audio Hardware Device Non-realtime Renderer, never a real device.

14. Test-driven porting

Who this is for: the porting developer. After it you know which test proves what in a port and in which order to run them, and you can test one newly ported rule from the first lookup to the cycle.

A port has something most software never gets: a finished specification that runs. The Unity game already does everything the port must do, so every test in a port asks one question - does the port do, here, what Unity does here - and every expected value can be READ from the game's files or MEASURED from Unity. This chapter turns that into a method, and ends with the procedure for one newly ported rule.

It points to other chapters instead of repeating them: Chapter 9 for the verification procedures (the gates, proving a route offline, conformance over every key, looking at photos), Chapter 12 for the headless Unity tools in full, Chapter 8 for measuring a Unity rule, and Chapter 5 for the game-code method these tests serve.

What makes a test a port's test

  • Its expected value comes from Unity. It is READ (from the game's code or data, with the file and line) or MEASURED (from a Unity run, with the run named). A value typed from memory tests the memory; a value copied from the port's own output tests the port against itself.
  • It can fail. It has been seen to fail on a planted wrong answer. Until then a green result says nothing: a check that has only ever passed cannot be told apart from one that is switched off.
  • It says what it examined. A test that judged nothing reports that it judged nothing, and that report is a failure, not a pass.

The Unity Test Runner is not a layer

Run from outside, Unity's Test Runner launches a second, full Unity Editor that imports assets, takes the foreground window on every assembly reload and throws modal progress dialogs. On the reference port its owner could not use the machine while one ran. A subset run starts the same Editor, so a smaller run is no safer.

So the toolkit's Unity test command (my_unity.py) refuses, exit 3, while .UNITY_TESTS_DISABLED exists at the toolkit root, and pillar 10 of the cycle (u2ue cycle, the toolkit's recurring self-check; "The cycle", below) checks on every run that the file is still there. A test that truly needs a live Editor - a real scene, AssetDatabase, UnityEditor.* - stays unrun, the report says so, and the owner decides. "Compile-verified headlessly, suite not run" is an honest report; "it works", from a test that did not run, is not.

The layers, cheapest first

flowchart LR
  A["dotnet test: the model's rules"] --> B["headless_nunit: Editor-folder tests"]
  B --> C["typecheck: Unity still compiles"]
  C --> D["parity + digest: the same bits on every runtime"]
  D --> E["conform: every key on numbers"]
  E --> F["photo: LOOKED at, last"]
layer command a pass proves it cannot prove
pure rules dotnet test <Model>.Core.Tests a moved rule gives Unity's value on CoreCLR Mono's bits; that Unity still compiles
Editor-folder tests py headless_nunit/headless_nunit.py --test <file> the test passes on the project's freshly compiled code, no Editor anything that needs UnityEditor, AssetDatabase or a scene
typecheck py typecheck.py the Unity project compiles as Unity would compile it that anything behaves
parity py -m u2ue --project <game> parity every runtime agrees by the bit, or differs only where characterised that the rule is right - only that it is the same
Unity's Mono py -m u2ue --project <game> digest run ... Unity's own runtime gave these bits, no Editor that the Editor would, until digest faithful measured it
conformance py -m u2ue --project <game> conform ... each key's built asset computes what Unity's does, per emitter how it looks; what the probe was blind to
photos py -m u2ue --project <game> photo once LOOKED at, the frames confirm the numbers anything, on their own

Pure rules: dotnet test

The game's rules move into an engine-free model (Chapter 5), and a moved rule is first tested in the model's own test project, <Model>.Core.Tests: written by u2ue scaffold, NUnit on net8.0, one test per moved rule, its expected value the one the Unity build gives. Nothing opens, and the model's gates (u2ue check --only model) have already kept the engine out, so the test tests the rule.

The toolkit's runtime library is tested the same way, and its tests show the shape to copy:

dotnet test u2ue/runtime/U2ue.Runtime.Tests

TrailLawTests replays the TrailRenderer law against Unity's play-mode bake (72 frames, 15 baked meshes, every point and vertex compared), and the same file carries the replay's plant: A_Wrong_Time_Fails_The_Replay runs the frames with a trail time of 0.45 instead of 0.5 and requires a mismatch. Without the plant, the replay would pass a law that ignored its time.

A version trap: the scaffolded tests use NUnit 4 (4.0.1), but Unity's NUnit is 3.x, and NUnit 4 moved Assert.IsNotNull and its family to ClassicAssert. Write a test that must also compile inside Unity to NUnit 3; that is why the headless runner pins 3.14.0.

Editor-folder tests: headless_nunit.py

Many Unity projects keep NUnit tests in an Editor folder, and most of them exercise data and logic, not the Editor. headless_nunit.py compiles the project from Unity's own compiler command line and runs those tests with no Unity process:

py headless_nunit/headless_nunit.py --test <Assets/.../Editor/XTests.cs>
py headless_nunit/headless_nunit.py --test A.cs --test B.cs --filter "FullyQualifiedName~Resolver"

Exit 0 all passed, 1 a test failed, 2 nothing ran or the filter matched nothing, 3 an environment or compile failure. What it cannot run fails loudly: TypeLoadException, MissingMethodException or FileNotFoundException, naming the member. A pure member is added to headless_nunit/UnityShimCore/Shim.cs; anything else needs a live Editor, and the test is left unrun and said so. "It lives in an Editor folder" is never by itself a reason to reach for the Unity runner.

The tool names its Unity project and install folder in its own constants (it predates the project file), so on another project you edit them first. Chapter 12 has how it works, what it cannot run and the traps it absorbs, including the one that lets a mutation "pass": read the printed MVID line every time.

Does it compile: typecheck.py

Unity has already written complete compiler command lines to disk, the Bee .rsp files. typecheck.py reuses them with Unity's bundled Roslyn and compiles both assemblies, the Editor one against the runtime assembly it has just built, so the answer is Unity's own, with no Editor:

py typecheck.py                         # both assemblies
py typecheck.py --as-head [--keep <path>]
py typecheck.py --model-from-source     # against the model's source, not its installed DLLs

Exit 0 clean, 1 compile errors, 2 could not run the check, and the tool says in as many words that 2 is not a pass. --as-head asks whether a fresh checkout would compile: a working copy can compile while a checkout does not, when code references files never checked in. Use --model-from-source when the Unity project uses the model's built DLLs. It proves the code builds, not that it behaves, and its last line says so. Chapter 12 has every option and the traps it handles.

The same bits on every runtime: u2ue parity

A rule that passes on CoreCLR can still answer differently on Unity's Mono. Chapter 5, step 7 is the method, with the reference port's real output. Each runtime writes a digest, one key=value row per case with every float as its bit pattern, and u2ue parity compares every row across every runtime found:

py -m u2ue --project <game> parity                       # exit 0 agree, 1 a row differs, 2 refused
py -m u2ue --project <game> parity --require Unreal      # refuse unless Unreal's digest is there
py -m u2ue --project <game> parity --characterise        # write the allowance from the digests on disk

Bits, not text: Mono and .NET spell identical bits two ways, and as text, an early pilot of the reference port reported 230 mismatches that did not exist. The allowance, <parity.dir>/logic-allowance.json, keeps parity a test, not a list of excuses: a differing row is red unless the allowance pins that row to its exact bits and to one ULP, so a new row, a moved value or a wider gap stays red, and --characterise refuses any gap wider than one ULP (logic_diff.py's selftest proves all four refusals). Characterising needs a measured cause and never turns a gate green; a fix that moves Unity's own values is the owner's decision.

The trap that costs most: the cases' inputs must be exact on every runtime - integer arithmetic, each written to the sheet (the digest, which records every input as an _in row too). Inputs made with float maths measure their own drift (Chapter 5, step 7).

Unity's answer with no Unity: u2ue digest

Parity needs Unity's digest, and the Editor is the expensive place to get it. u2ue digest gets it from Unity's own runtime, with nothing opening and nothing taking focus:

py -m u2ue --project <game> digest run --entry <Ns.Cases.Build> --cases <Cases.cs> [--refs X.dll ...] [--dir DIR] [--editor DIR]
py -m u2ue --project <game> digest faithful

The model is built Release for netstandard2.1, as Unity loads it. The configuration is part of the answer: Mono keeps float intermediates wide wherever the IL leaves them on the stack, and a Debug build stores them to locals instead. Measured on the reference port: one seeded battle replayed on Unity's Mono from a Debug build forecast two turns unlike Unity's, and from the Release build it forecast every turn as Unity did. --editor names the Unity install when the project names none; a run that finds no Mono is refused before either sheet is written.

run compiles the cases twice, for CoreCLR (logic-Headless.txt) and with that Unity version's own compiler and Mono (logic-UnityMono.txt). logic-UnityMono.provenance.json names the Mono and whether it is MEASURED faithful to the Editor for this Unity. That label is the point: Unity's Mono is Unity's runtime, not the Editor. digest faithful measures it against a digest the Editor wrote (Chapter 12); on a Unity with no such measurement the provenance reads UNMEASURED. The selftest proves the standalone Mono both ways: standalone Mono must reproduce the Editor's digest AND must NOT match the CoreCLR one, or the comparison could not tell the runtimes apart.

Every key on numbers: u2ue conform

For assets that simulate - effects, today - this layer compares Unity's state with what the built Unreal asset computes, over every key, on numbers; Chapter 9 has the procedure. It comes after parity because it spends both shared resources (a window in the owner's editor and the one headless Unreal), and its diff is heavy (on the reference port: 673 keys, a 1.7 GB read-back), so the cycle reads the newest stamped report instead (conform latest) and refuses as STALE a report another judge made.

It comes before photos because it sees what a photo cannot: on the reference port one class-wide read found every non-prewarmed burst born one warm-up tick late, 121 of 121, after nights of per-effect photos had not. Its selftest includes a planted 0.03 s late birth and an emitter missing on one side, which must be named, never dropped.

The picture, last: u2ue photo

py -m u2ue --project <game> photo [--tag TAG] [--times 0.1,0.3,0.6,1.0]

Photos run last, and are never skipped. Last, because a metric over pictures can reward the wrong thing (Chapter 9, rule 3: a render that went black scored better). Never skipped, because data can be right about a worthless result: a generated level once passed every file-level check while carrying the same 145 prefab instances as an empty level, where the hand-made level it was meant to match carried 1722.

A photo run is judged by its capture (u2ue/capture.py), never its exit: judged by its exit alone, a photo step could read "ok" for a run that drew nothing. A sheet is evidence only once LOOKED at.

Why the order matters

  • Cost. The first three layers need only the machine (the second and third read Unity's install and the project's last Unity compile, with no Editor running); conformance needs the owner's editor and the one headless Unreal; photos need the Unreal and a person's eyes. A rule that would have failed dotnet test in seconds must never be what fails a conformance run hours later.
  • Trust. Numbers before pictures: a look covers one draw, and data that proved itself says what the picture should show. A skipped layer is not a passed layer.

Determinism across runtimes: what the field knows

A port that runs the same C# on Unity's Mono and on CoreCLR (an UnrealSharp host, a headless test run) meets this directly: parity compares the runtimes' answers by float bits. This section says which differences to expect, which to audit for, and how far byte identity can be relied on. It was read as raw text from the standards, the .NET runtime's GitHub issues and the vendors' own documentation; where a point rests on one author, or was not checked against Unity's own build, the text says so.

What the standards allow

ECMA-334, the C# language standard, section 8.3.7 "Floating-point types", says floating-point operations may be performed with higher precision than the operation's result type, and that an explicit cast forces a value to its type's exact precision. Its own example of the hazard is an expression of the form x * y / z, where the multiplication leaves the double range and the division brings it back: the wider evaluation can give a finite result instead of an infinity (standard, Microsoft's copy).

ECMA-335, the CLI standard, Partition I section 12.1.3, says the size of the internal floating-point representation is implementation-dependent, as long as it is at least as precise as the value it represents; that freedom ends at an explicit conversion (conv.r4 or conv.r8), after which the value must be exactly representable in its type (PDF).

So a one-ULP difference between runtimes is not a bug: both specifications license it. Byte identity across Mono, CoreCLR and a headless run is an observed property of today's builds, not a guarantee; it can break on a Unity or .NET upgrade with no change to the game's code.

Fused multiply-add, and Mono's float32

A natural first suspect for cross-runtime float drift is the JIT fusing a multiply and an add. The .NET team ruled that out on purpose:

  • dotnet/runtime#64591 proposed emitting fmadd for x * y + z. The owner of System.Numerics closed it: a fused operation returns a different result for many inputs, so it is a value-changing optimisation, not IEEE 754 compliant, and not a safe or legal default. Clang and MSVC allow it only under ffast-math and fp:fast; GCC defaults to -ffp-contract=fast.
  • dotnet/runtime#64604 then set -ffp-contract=off for GCC builds of the runtime itself.
  • dotnet/runtime#12753, a configurable fast-math mode, was closed unimplemented. .NET has no fast-math mode.

The better suspect is Mono. Mono's creator wrote (2018-04-11) that Mono, decades earlier, performed all 32-bit float computation as 64-bit while storing the data in 32-bit locations, and later added an opt-in "float32" mode, --O=float32, to do 32-bit float operations in 32 bits (link). That is a one-ULP generator on a float multiply-divide: Mono computing a*b/c at double precision and rounding once at the store, CoreCLR rounding to float32 after each operation, both legal under ECMA-335 section 12.1.3. Which Mono build and which float32 setting a given Unity version ships was not verified.

The experiment. ECMA-335 says extra precision is discarded at an explicit conversion, so compare (float)((float)(a * b) / c) against a * b / c in a differential harness: if the casts close the gap, the fix is explicit float locals. On the reference port they did (Chapter 5), but that result fits both suspects, so it could not tell them apart; the toolkit's first diagnosis read it backwards (logic_diff.py records the correction). What settled it was which runtime differed: on all 35 characterised rows Unity's Mono was the odd one out, and the two CoreCLR runs agreed on every row. A fusing CoreCLR would have made them the outliers.

Two divergences that are not rounding

Float-to-int casts differ between Mono and CoreCLR, and the difference is open. dotnet/runtime#119821, filed 2025-09-17, shows (int)(float)int.MaxValue giving 7fffffff on CoreCLR and 80000000 on Mono. A .NET architect replied that since .NET 9 float-to-integer conversions saturate on CoreCLR on every architecture, that this was not fixed on Mono, and that these conversions are undefined behaviour there. dotnet/runtime#100368 tracks it (the .NET 9 change).

System.Math transcendentals call into the platform's C runtime, and one .NET build was measured to differ between operating systems (dotnet/runtime#12753, a .NET 3.0 preview):

call Windows macOS
MathF.Asinh(0.48549962f) 0.46820483 0.46820486
MathF.Acos(0.57316583f) 0.96043230 0.96043223
MathF.Log2(1/3.0f) -1.5849625 -1.5849624

dotnet/runtime#9001, which asks for System.Math and System.MathF to be implemented in managed code, is still open. Only Math.Sqrt is IEEE-guaranteed. One author's Unity harness, run on Windows (Intel and AMD), Mac, Android, iOS and WebGL, agrees on the shape: only the trigonometric functions gave non-deterministic results; arithmetic, comparisons and int / float casts matched (link).

Both divergences are likelier, larger and cheaper to find than a ULP.

Fixed point

For bit identity across arbitrary hardware, fixed point is the standard answer in the vendors' own documentation: Photon Quantum (Q48.16 in one long; it warns that converting from a float inside the simulation desyncs, link), mas-bandwidth/fixed (which names fused multiply-add, libm transcendentals and -ffp-contract as what differs across compilers and architectures, link), Klotho (32.32, explicitly targeting Mono and IL2CPP, Unity's C#-to-C++ build backend, link), and Factorio's MapPosition (a 32-bit integer with 8 fraction bits, link). The canonical 2010 article "Floating Point Determinism" made float determinism conditional on the same compiler and the same architecture (link), and its author's company now ships the fixed-point library above. Two JITs are two compilers, so byte identity across Mono and CoreCLR is outside what anyone claims to rely on.

What fixed point costs

Quantum's documentation names the costs: the fraction is limited, never as accurate as a double; two parsing routes can disagree on one machine (FP.FromFloat_UNSAFE(1.1f).RawValue != FP.FromString("1.1").RawValue); FP.UseableMax, 32767.9999847412, is the largest value that can be squared without overflowing; precision holds in about 0.01 to 1000 and is lost multiplying very large or very small numbers and dividing back; and FP cannot be a C# constant, so a constant is written as its raw long with the decimal in a comment. A shipped RTS that moved to 64-bit fixed point adds that no third-party library can then be used (link). Quantum's own worst case is multiply-then-divide, the C# standard's float hazard: fixed point turns that one-ULP disagreement into a bounded precision loss both runtimes agree on, an improvement, not the problem gone.

What desynced shipped games

Every shipped lockstep success in this literature (lockstep: every player's machine runs the same simulation from the same inputs, so all must compute the same result) is one binary on one architecture: Supreme Commander and Demigod, quoted in the 2010 article, set the FPU's (the floating-point unit's) precision and rounding at start-up (_controlfp(_PC_24, _MCW_PC), _controlfp(_RC_NEAR, _MCW_RC)) and asserted both every tick; MotoGP, quoted there too, could not share replays between Xbox and PC. And the published desync causes are overwhelmingly not floating point:

  • memory bugs: uninitialised variables, dangling pointers, a reused address (Supreme Commander, link);
  • an ambiguous sort comparator that different compilers' sorts order differently (Factorio FFF #52, link);
  • printf formatting: gcc printing 1e-05 where VS2013 printed 1e-005 (FFF #108, link);
  • serialisation: nil as a placeholder for a cyclic reference deletes the key and changes the iteration order; a cached value recomputed instead of saved (FFF #340, link);
  • random-call counts that must match inside the simulation (Age of Empires, link).

Not needing bit identity at all

The modern alternative is not to need it. Valorant's server is authoritative and some divergence from a client's prediction is accepted; its fixed 128 Hz step makes the comparison like for like, not the bits equal (link). Rocket League's networked physics is server-authoritative too, and corrects a large difference by reverting and re-simulating; the words determinism, float, double, precision and bitwise appear nowhere in its 182 GDC slides (link). That is a tolerance test, not an equality test.

The line for a port: a byte-identical event log across runtimes is a stronger oracle (the source a test's expected answer comes from) than any shipped game in this literature attempted, and it is worth keeping as an instrument, but no specification backs it. The cheap moves, in order: run the explicit-cast experiment; audit for float-to-int casts and for System.Math calls other than Sqrt; then decide deliberately whether the contract is byte identity or logical parity with an ordering-and-tolerance comparison, because the first will one day break on a toolchain upgrade that the second would survive.

Write the test first

The judge before its trial

A judge (u2ue/judge.py) holds a record - a read-back, a capture, a case record - to a measured rule or to Unity, and must fail on its plant. Chapter 8 gives the order for a measurement: the judge, its plants, then the bake. A converter route's trial keeps the same order, because a judge written after the data is fitted to the data and passes whatever happened.

Judges are read off the trial specs' judge steps (<lane>/trials/**/*.json), never listed by hand, so the list cannot drift from what runs:

py -m u2ue --project <game> judge             # each judge, the trials that run it, how its plant is proven
py -m u2ue --project <game> judge --prove     # runs each judge's --selftest; exit 1 when one fails or has no plant

--prove reads PLANTS (its --selftest refused its planted faults), DECLARED (a trial declares a plant for it), NO PLANT (it has only ever passed) or FAIL. A trial step declares a plant beside its judge:

{"judge": {"argv": ["{lane}/<route>/<route>_check.py", "{dir}/<read>.json"],
           "plant": {"argv": ["{lane}/<route>/<route>_check.py", "{dir}/<route-off read>.json", "--plant"]}}}

u2ue trial runs the judge, then the same judge on the record it must refuse - the route-OFF read, a planted shift - and a plant that passes FAILS the step by name. A plant the judge's own verdict already requires refused is declared with in_run. When this became a cycle check on the reference port (2026-10-16), three of its judges had only ever passed.

A gate that has only ever passed

Every gate carries planted defects in its own --selftest, and the null case: an unperturbed input must PASS, or a gate that refused everything would pass its own plants. The headless NUnit runner's selftest is the pattern: a planted passing test exits 0, a planted failing test 1, a filter that matches nothing 2.

The most expensive failure is a check that passes without examining anything, because it turns "unknown" into "verified". On the reference port a test command printed None/None passed ... no regressions and exited 0 for a reply it could not parse; a read got 0 of 150 frames for all six systems of a trial, exited 0, and two judges then reported "0 judged" as if they had looked, which is why every read now writes a capture summary (u2ue/readback.py). The repair was never more checking. It was making each check state what it examined, so an empty examination reads as empty. An empty selection is a refusal, never a quiet skip.

Prefer an oracle from what the thing must do over a threshold. An ON/OFF comparison of a light-scattering effect once differed in 315k pixels; but that effect only ever adds light, and the signed difference was brighter in 152,782 pixels and darker in 155,186 - an even split, which is scene motion between two renders.

A plant must move what is judged

A plant proves something only if it changes the input the judge judges. On the reference port plants proved nothing in four ways:

  • the check read its default file instead of the planted one - check which file it opened;
  • the planted value equalled the measured one in every case of the trial - a plant acts on what the judge actually found;
  • the code refused the plant's input before any engine call, so it tested the refusal, not the route;
  • a patch was proven against a stub, while at run time a cache wrapper over the called function kept its old signature - run the selftest of whatever is installed over the callee.

Widening a gate, and proving it still fails

A gate that walks one folder stops seeing what the port moves out of it ("Rules that keep tests honest", below). When a gate's scope is widened, its plants are re-run and one is added inside the new scope; otherwise the widened gate has only ever passed where it now claims to look.

A selftest on synthetic input proves the matcher, not the aim. A gate that refuses engine primitives standing in for real assets plants primitives in temporary folders, so a second proof copies the game's real engine-side code folder, plants one offender in the copy and scans it, proving the gate still walks the files that matter. A selftest of a gate is not a run of it, either: run the gate itself too.

A new gate that refuses content also runs offline over the whole existing corpus before a long build relies on it. On the reference port a mesh-import gate proven on two files went into a build of about two hours and refused 3 of 46 meshes it should have passed; 7 emitters vanished from three effects. Checking all 46 offline took about two minutes. A refusal of content that drew correctly yesterday is the gate's bug until shown otherwise.

Mutation: does any test notice?

py -m u2ue --project <game> uml tests <Name> separates called inside a test, merely mentioned in a test file, and not present - and still says only mutation answers whether a test would notice a change. py -m u2ue --project <game> mutate <mutations.json> asks it:

  • The project file's mutation block names what to copy - copy, folders or globs such as Shared/*.cs, from its root - and the test project, test (Chapter 3). Every run copies them fresh into a temporary folder and works only there, so no open Editor, no other build and no other lane sees a mutant, and the project's own files are never written. A copy whose build files hold a step that can write outside it (Exec, Copy, a pre- or post-build event) is refused.
  • Each mutation is a row: the file, a label, the exact old text (its anchor), the new text, the claim the tests protect, and optionally a dotnet test --filter. A rename is not a mutation: it only breaks the build, which every test "catches" for free. Every row changes behaviour and still compiles.
  • The tests run on the untouched copy before any mutation and again after the last; the first must pass, or the verdicts between mean nothing, and the run is refused. Then one row at a time is applied, the tests run, and the file is put back byte for byte.
  • Each row is CAUGHT (a test failed), SURVIVED (all passed - write the test that notices), COMPILE-BREAK (not a mutation), NO-RESULT (no test summary even after retries; a held file is retried, never counted) or ANCHOR-MISS. The run ends MUTANTS NOT CAUGHT n of m, each survivor with its unchecked claim, and exits 0 only when every row is caught.
  • An anchor that matches zero times or twice is an ANCHOR-MISS, counted as not caught: the harness refuses to guess. It can mean the source moved under the row (measured on the reference port, 2026-09-07: a timeline that had grown from 11 beats to 13), and then the fix is the anchor, not the harness.

Measured on the reference port on 10-21, with its own harness's 13 rows as a mutation file: the copy took 1,804 files (six projects, and the files the test project links in from elsewhere), the 64 tests those rows protect passed on the untouched copy, and the run ended MUTANTS NOT CAUGHT 0 of 13 - every row failing exactly as many tests as that harness counted on 09-07, two harnesses agreeing on all thirteen. That harness itself can no longer run: four of its eight rule files have since moved into the model's presentation project, and it looks for them only where they were. The same morning, four of five mutants planted in the project's own tree read no verdict at all, because another build held the DLL (MSB3021); the copy has no such neighbour.

Add a row whenever you add a rule.

The console is the headless test

A compiler proves the code builds; the console proves it ran. On the reference port three faults in one session passed every other instrument and were obvious in Unity's console within one frame (Chapter 12 lists them). console_check.py reads a running Editor's console through the editor's HTTP bridge (Chapter 12; the bridge does not ship yet, so your project needs its own) and reports only what is NEW. Use it as a gate:

py console_check.py --reset                      # mark everything seen, before the action
py console_check.py --label "what I just did"    # after it: exit 1 when NEW errors appeared

New errors stop the work. Exit 2 means the bridge was unreachable or refused - not a pass. Pair it with a Play cycle when a change touches rendering. Reading the console starts nothing and takes no focus, but it needs an Editor already running. Chapter 12 has its watermark, how it collapses repeated rows and counts Unity's own noise apart, and a known gap on a long console.

A fresh record is not a fresh build. On the reference port a Unity-side recording was triggered after a model change, before the Editor's domain reload had settled. Unity re-recorded 17 s later on the OLD assembly: the recompile had failed on one access error (CS0122), so the Editor kept the old code. The record was newer than the DLL, every timestamp check passed, and the tests failed identically. console_check showed the compile error. So the order is: typecheck.py before anything that recompiles, wait until the reload has finished, record, console_check, then the tests.

The cycle

Pillars and verdicts

u2ue cycle holds the toolkit to its promises when a work cycle ends or a report is about to be written. A pillar is one promise the product makes; a check is one command the toolkit already runs, and the rule that reads its output as a verdict.

py -m u2ue --project <game> cycle                 # every pillar; exit 1 when any pillar is FAIL
py -m u2ue --project <game> cycle --pillar 2 3    # only these; a partial run never becomes the baseline
py -m u2ue --project <game> cycle --dry           # list the pillars and checks; nothing runs
pillar the promise
1 AUTO-PORT every asset family that is not logic ports with no human step
2 AI LOGIC PORT Opus, pointed at a game through the skill, ports its logic
3 HUMAN ERGONOMICS every concept a named class; diagrams generated from the code and gated
4 AUTOMATION TOOLS SHIPPED the Unity and Unreal automation a port needs ships in the package
5 PROOF AND CONFORMANCE every judge has a plant that fails; conformance read from data
6 MEASURED KNOWLEDGE every Unity rule measured by a probe case, stored per Unity version
7 GENERIC, NOT ONE GAME adapters and project files, no hard-wired paths in the core
8 PACKAGING AND RELEASE a UPM (Unity Package Manager) package that installs into a fresh Unity and a fresh Unreal project
9 SPEED AND PROOF OF VALUE the porting speed and the percent-identical family, from records
10 SAFE OPERATION the toolkit never disturbs the person using the machine
11 RUN INFRASTRUCTURE pinned, resumable runs from data, stoppable between steps
verdict meaning
PASS the check ran and its rule holds
FAIL the check ran and its rule does not hold - red stops the cycle
HELD it fails ONLY in the way a recorded open decision of the owner's says it must; failing any other way is FAIL
ABSENT no check exists yet; never counted as PASS - it names the work that would build it

A pillar is FAIL if any check is FAIL, ABSENT if no check of it ran, otherwise PASS, with HELD checks shown beside it. Red stops the cycle with exit 1, and the record keeps 40 lines of the failing check's output - the lines saying FAIL, REFUSED, ERROR or Traceback first, then the end - so it says why without a re-run.

A HELD check names its decision and the failing lines it explains; one more failing line, or a failure that prints none, is FAIL, so a new failure can never hide behind an old decision. A trend check reads a number and a direction it must not move in (the share of conforming emitters must not fall); the first cycle is the baseline, and a number not read is FAIL.

The record and the baseline

Each run writes <work.records>/cycle/cycle-<stamp>.json; a full run also writes cycle-latest.json, which the next cycle trends against. A trend that FAILED keeps the previous value as its baseline, marked baseline_held: writing the regressed value would make the regression the new bar.

Read a record by its FAIL rows first, then its HELD rows, then its ABSENT rows. A HELD row waits on the game's owner, not on the toolkit: for example, a scene fidelity gate held while whether to keep an imported level's deliberately changed lighting is still undecided.

What the cycle does not run

The cycle checks the toolkit against a project; it does not run your game's own tests. dotnet test <Model>.Core.Tests and the project's parity are not cycle checks (pillar 2 runs the project's model gates, the runtime library's tests and the parity tool's selftest). Run them yourself; py -m u2ue --project <game> logic reads where the logic port stands, runs check --only model and parity, and names each test run it does not start as NOT RUN, with its command.

u2ue check: the selftests and the gates

py -m u2ue --project <game> check                      # all four parts
py -m u2ue --project <game> check --only selftests [--tool console_check.py ...]
py -m u2ue --project <game> check --only gates         # the field gates over this project's IR
py -m u2ue --project <game> check --only facts         # the measured rules' Unity versions against the project's
py -m u2ue --project <game> check --only model         # layer_gate and host_gate on the engine-free model

The selftests run with every U2UE_, U1E_ or VFXPORT_ variable left in your shell dropped and the project's own U2UE_ paths set, so a switch you exported once cannot change what a plant meets. They run below normal priority, launching neither Unity nor Unreal; exit 1 when any fails. Each tool's last run, its exit and its seconds are in u2ue/survey/pt1_selftests.json. A selftest that is not run says its measured reason: the package skips one that corrupts and restores a plugin DLL an open Unity editor loads, and a project file can name its own (the reference port's skips one that launches Unreal). Selftests nobody runs rot: the first survey found three broken unseen and both field gates red. Chapter 21 lists every selftest; Chapter 18 has how a tool's selftest is registered.

Rules that keep tests honest

Never re-record a baseline to make a red gate green. A baseline, an allowance or a fingerprint is re-recorded only when the change it records is intended, with the reason committed beside it. The cycle enforces it for trends, parity for allowances; this rule does everywhere else.

A miss is UNKNOWN, never ABSENT. The toolkit's code readers are lexical: a call through an interface, a delegate, reflection or a UnityEvent wired in a prefab is invisible to them, and uml callers and uml tests print UNKNOWN when they find nothing. An ABSENT you write needs the level above: name the search that would prove it, and check the container (a field missing on a record may live on the group holding it), a second rule of the same shape, whether you actually ran the tool, and whether a later pass writes more.

Check whether the code moved before believing a red gate. A gate that walks only the Unity tree reports what the port moved into the model as ABSENT. On the reference port (2026-09-29) three gates did so in one day: the class-model gate said a method did not exist while it sat in the model (both of its channels walked one directory), another reported four abilities no longer called whose calls had moved one hop, and the requirements checker silently covered less each time an annotation moved. py -m u2ue --project <game> uml where <Name> walks the code roots and the model together. Then widen the gate and re-run its plants.

A call site is not coverage. A test can call a method in setup and assert on something else. Say "called from N test files", never "covered".

Re-run a red test in a file another worker just wrote. Compare its modification time with the clock and re-run before investigating. On the reference port a test failed identically three runs in a row while its owner had fixed the line a minute earlier; the next run was green. Never patch a live worker's file: record the finding with its file and line, and let the owner land it.

Snapshot suites when work lands concurrently. A suite that reads expectations from data at run time and compares them with code compiled earlier straddles any landing that changes both, so compare the failing area's sources and data with the compiled assembly's time before diagnosing. On the reference port twelve such failures were diagnosed as drift; an hour later the suite was green with no action taken. A compile break in a file saved a minute ago is the same: poll the build until it settles.

Test an agent, or a skill, by running it. u2ue/survey/skill_gate.py checks that every command a skill names exists and each step has a RUN and one DONE WHEN; it cannot see what a model does with the text. On the reference port a static audit of six generated agent definitions found two defects; running one on a bounded, read-only item found five. Grade the run's report against the definition, fix the generator, run it again.

An instrument that answers anyway is worse than one that will not answer. Make an instrument refuse when its input is stale: exit 2 when a coverage report is older than the source it describes, and exit 1 when a to-do list was made from a tree that has since changed. On the reference port a stale coverage report said 15 of 100 files at 18.3 percent where a fresh one said 90 of 101 at 74.1 percent: the opposite conclusion.

Requirements and tests

// REQ: annotations

Every feature traces to a requirement through a // REQ: comment on the rule. py -m u2ue --project <game> req checks every citation under the project's requirements.roots (or the paths you give it) against the requirement documents the project file names (Chapter 3), and --unresolved lists only the ones that fail:

  • A citation begins with a source's name. A lines source is a text file cited by line - Requirements.txt:12, :12,40, :21-27, :12 + :40 - and holds when a cited line exists and says something: a blank line or a rule of dashes is not a requirement. It can also be cited by an id a line starts with, Requirements.txt REQ-MOVE-01, which survives lines inserted above it where a number does not.
  • A sections source is a document. It holds when the file exists and every id the citation names (Design.md R-3) is defined in it - at a heading, a table row or a list item; a sentence that mentions an id does not define it. A source named by a glob (*.md) over a list of folders finds the document in one of them, and a document found in two is ambiguous, so it does not hold.
  • An entries source is a folder - a spreadsheet's tabs exported one file each, say. It holds when the words after its name name one of its files, case and separators not counting (Tile Effects is Tile_Effects.csv), or an alias the project declares does. Never a substring: Stat does not name Status_Afflictions.
  • A citation that begins with one of the project's tags - a phrase or a pattern, plumbing, bug-\d+ - is TAGGED: no designer requirement behind it, declared, the ABSENT half of READ-or-ABSENT. A tag that also cites a line still needs that line to say something.
  • One comment holds several citations, split on |, ; and + - never inside brackets or quotes.
  • Anything else is UNRESOLVED and goes to the designer, and the run exits 1; so does a run that finds no citation at all. When one offset explains every cited line of a citation (each one's neighbour at +N says something), the run says so and counts those together: one fix, not many. Nothing is rewritten - a citation's owner moves it.

Measured on the reference port on 10-21, with the same documents and tags as its own checker: 3,613 citations, 796 that hold, 1,636 tagged and 1,181 unresolved, 1,073 of those one offset of +1 in one requirements file. The two checkers' verdicts differed in five kinds, each traced and none unexplained. Its checker passed 957 tags whose cited line is blank (marked STALE). It split 78 comments inside parentheses, 44 of them into a fragment it then reported unresolved. It matched spreadsheet tabs by substring, and 7 of its 10 such matches named a different tab than the words do. It also missed 3 tags followed by a full stop, and an id cited in a line file.

Two warnings, both measured on the reference port. A check that reads only the paths you hand it covers less each time annotations move with the rules into the model, so name the model's folders in roots too. And cite by id where the document has ids: one line inserted near the top of a requirements file left 1,073 line citations pointing one line high.

The discipline it serves: every new feature gets a test, linked to the commit that adds it and to its requirement; a feature with no requirement gets a stub line in the requirements, marked for the designer, before it merges.

The class model gates

The class model comes first: a new concept gets a named class before code is written around it, and diagrams are generated from the code and gated, never hand-drawn and trusted.

  • The class-model gate, py -m u2ue --project <game> uml check --doc <use case model .md>, looks up every identifier the document names in the class model of the game's code roots and the model; a name the extractor lacks is asked of an independent text scan first. When the channels disagree it ABSTAINS and says where to settle it; it FAILS a name written as a call only when both agree it is absent. It also refuses a document with no PROBLEM STORY section (the problem told in words, which the use cases are drawn from), no primary actor or no EPIC, and an epic of fewer than 3 or more than 11 steps. The key case of its selftest is CAN-THE-GATE-FAIL: a fabricated name must be refused.
  • The concept gate, u2ue/survey/concepts_gate.py, holds the toolkit's own concept model (u2ue/CONCEPTS.md) to its code: a row marked EXISTS must name path.py:Class, and that class must be in that file. Chapter 22 has the model it checks.

Procedure: a test for a newly ported rule

Scope: one rule of the game, moved into the engine-free model. Precondition: the model is scaffolded (u2ue scaffold) and its gates pass. Minimal guarantee: a step that cannot run is reported as not run, never as passed. Success guarantee: the rule has a test that was seen to fail, gives Unity's value by the bit on every runtime, cites its requirement, and the cycle reads PASS or HELD by a named decision. Trigger: a rule is about to move out of the Unity tree.

  1. Find the rule. py -m u2ue --project <game> uml where <Name> names its type, file and line - proof that the name exists. py -m u2ue --project <game> uml callers <Name> lists its candidate call sites; a miss is UNKNOWN.
  2. Read its inputs and Unity's answer. Constants from the code, with file and line; serialized values from the asset, py -m u2ue --project <game> data --from <Assets/...prefab> --script <ClassName>, never the C# initializer. The expected value is the one the Unity build gives, read from a record or measured (Chapter 8); if neither, stop and measure it.
  3. Write the test before the move. One NUnit test in <Model>.Core.Tests, its expected value from step 2, its source in a comment.
  4. Move the rule unchanged, and gate the model. A behaviour change is a separate, named decision. py -m u2ue --project <game> check --only model proves no engine namespace or platform member came with it.
  5. Run the test. dotnet test <Model>.Core.Tests - green proves the moved rule gives Unity's value on CoreCLR. Not trusted yet.
  6. Make it fail on purpose. Change the rule's behaviour so it still compiles - a constant off by one, a comparison turned round - and rerun step 5: the test must fail with an assertion naming the value. Restore. For a standing proof, keep the change as a row of a mutation file and run py -m u2ue --project <game> mutate <mutations.json>, which tries each row on a fresh copy and reports MUTANTS NOT CAUGHT 0 of n (the section "Mutation: does any test notice?" above). A failure that is only a compile error proves nothing.
  7. Prove Unity still compiles. py typecheck.py (with --model-from-source when the Unity project uses the model's built DLLs) - exit 0 proves the Unity project still builds around the moved rule. Exit 2 is not a pass.
  8. Run its Editor-folder test, if it has one. py headless_nunit/headless_nunit.py --test <Editor test.cs> - exit 0 proves it passes on the freshly compiled assembly; exit 2 means nothing ran.
  9. Answer the rule on both runtimes. Add its cases to the digest's case file, inputs exact and written to the sheet, and bump the digest's version. py -m u2ue --project <game> digest run --entry <Ns.Cases.Build> --cases <Cases.cs> writes the CoreCLR and Unity Mono sheets with no Editor; the provenance says whether that Mono is MEASURED faithful.
  10. Compare them by the bit. py -m u2ue --project <game> parity - exit 0 proves every runtime agrees on every row. A one-ULP row is diagnosed and its cause measured; only then, by the owner's decision, parity --characterise pins it.
  11. Check the console, when an editor is running. py console_check.py --reset before the Unity side recompiles, then py console_check.py --label "<rule> moved" - exit 0 proves the Unity build ran with nothing new in its console. With no editor running, the step is reported as not run.
  12. Cite the requirement. A // REQ: comment on the rule, then py -m u2ue --project <game> req <the model's folder> (the section "// REQ: annotations" above says what it checks) - exit 0 proves every citation holds or is tagged; exit 1 goes to the designer.
  13. Draw the slice. py -m u2ue --project <game> uml mermaid --focus <Type> draws it from the code, every member real; py -m u2ue --project <game> uml check --doc <use case model .md> proves every name the use cases use exists.
  14. See where the port stands. py -m u2ue --project <game> logic - each logic skill step DONE, NOT YET, JUDGED or NOT RUN, read from the records now.
  15. Close the cycle. py -m u2ue --project <game> cycle - every pillar PASS, or HELD by a named decision. A FAIL stops the work until it is fixed; it is never re-baselined.

Steps 1 to 8 spend no shared resource, steps 9 and 10 need no Editor, and step 11 only reads one that is already running.

15. Porting with Opus 5.5

Who this is for: the porting developer who runs the port with an AI model - which skills to load, how to keep a long session going, how to keep its tokens down, and how to check its work.

u2ue is built to be driven by an AI model: you point Opus 5.5 at the game's logic through the toolkit's skills, and the verbs carry the other asset families (Chapter 2 lists each family and its commands). This chapter also covers what running several agents at once was measured to cost. The model is never trusted on its own word.

What carries a port from session to session

The reference port was done by AI models working in Claude Code (Anthropic's command-line coding agent) over many sessions (u2ue/basis/tokens.json names the models each measured rate came from). Four things carried it from session to session, and a port of your own needs the same four.

  • A project rules file, read at the start of every session. It holds the iron law written as working rules (no guessing, no fallbacks, no toys, verify with both the data and the picture), the safety rules (never the Unity Test Runner, never the live editor someone is working in, one headless Unreal at a time), "fix the class, not the instance" (fix what produced a fault, not the one case seen; a one-off fix carries its reason), and the rule that UML class diagrams steer the work. Keep it short: every agent pays for it (below).
  • One task list on disk. Every item is a line with an observable a stranger could re-check (DONE WHEN: ...). The session reads it at the start of every item, because a session cannot see its own context being compacted (summarised to make room as it fills).
  • Memory notes, one fact per file. A trap is written down once, with its fix, so that the next session does not pay for it again. Two examples: a shell that rewrote the PATH so Unreal could not find .NET, and a heredoc (a shell's inline block of text) that ate backslashes.
  • Skills. A skill is a packaged procedure that the model loads when the task matches it. Besides the toolkit's two porting skills, the port used three general ones:
  • a long-run skill: finish the list, never stop at a turn boundary, verify before reporting, and when blocked, solve it or ask, never drift sideways;
  • a senior-dev loop for backlogs: waves of work, one driver for a shared editor, and an assessment after each wave;
  • a use-case skill: use cases from the problem story, and a class model from the source, gated so that a name the code lacks fails.

The package ships the long-run habit and the lookup order as skills of their own (below). The senior-dev loop and the use-case skill are not in the package.

Keeping a long port going

A model in a session does not keep going on its own. In the owner's experience, a session stopped after an hour or two whatever the list still held: it wrote a summary at a natural pause and waited. A port's logic is days of work, so two things keep it running, and the default path uses both.

  • In a session: the long-run skill (u2ue/skill/u2ue-long-run/SKILL.md). The list lives on disk, each item with an observable, and the session re-reads it at the top of every item. A summary is the last thing in a run, never a habit at the end of a turn: before writing one, the session checks whether an item is still open and takes it instead. When it is blocked it solves the blocker or asks one question, and it never drifts to an easier task next door. Ask for it in plain words ("finish it all") or load it by name.
  • Across many agents: a workflow. A script, not the model, decides what runs next, so nothing stops at a turn boundary. The reference port's extraction ran that way: one agent per coupled file, four gates per file, in order. Its record shows 81 agents in one run of close to sixteen hours.

u2ue port hands the AI stage over with both in mind. Its stop names the u2ue-logic skill to run with u2ue-long-run, and u2ue logic says the step it resumes from, so a new session picks up from the records instead of re-deriving the state.

The skills the package ships

skill what it is for read it when
u2ue/skill/u2ue/SKILL.md the entry point: price the port (estimate), run every stage a verb can (port), and take each stop to the skill or the person it needs "port this game to Unreal", with the Unity project open - the default way in
u2ue/skill/u2ue-logic/SKILL.md port a game's C# into an engine-free model behind seams, slice by slice, each step with its command and its DONE WHEN the logic port (Chapter 5)
u2ue/skill/u2ue-mvc/SKILL.md the shape the logic moves into - Model, View, Controller, commands in and events out - and the rule that sorts every MonoBehaviour into it deciding where a type's state, rules and drawing go (Chapter 5, "MVC")
u2ue/skill/u2ue-port/SKILL.md port an effect gap by the route protocol: census, a switch that starts OFF, proof, trial, LOOK, flip with evidence an effect the converter refuses (Chapter 7, Chapter 11)
u2ue/skill/u2ue-lookup/SKILL.md answer code questions from the index and the class model, read the file last; choose the agent before starting one before reading any file to find something; before fanning out
u2ue/skill/u2ue-long-run/SKILL.md finish a long list: one list on disk, an observable per item, a re-check before any report "finish it all", and any time a session is about to report with items open

The skill gate (u2ue/survey/skill_gate.py, pillar 2 of the cycle) holds every one of them to the toolkit: a command a skill names must exist, and a step written as ### Step N. must carry at least one RUN: line and exactly one DONE WHEN: line. A skill that sends the model hunting for a command that is not there fails the cycle.

Directing the model at a game

A session opens on where the port stands, never on a re-derivation:

py -m u2ue --project <game> logic          each step of the logic skill, judged by its own DONE WHEN; the step to take next
py -m u2ue --project <game> info           every path the project names, opened

What makes a prompt work, as it was learned on the reference port:

  • Name the observable. "Port this slice" ends when the model thinks it looks done. "Port this slice so that py -m u2ue --project <game> parity exits 0 and the slice's diagram resolves" ends when it does.
  • Give it the diagram, not a description. The logic skill's step 2 draws the class model of one slice before anything moves (py -m u2ue --project <game> uml mermaid --focus <TypeA> <TypeB>). The target diagram is the prompt: the model is asked to make it true, and the gate checks every name in it against the code. A prompt that carries a diagram cannot drift into a design you never saw.
  • Quote the acceptance sentence (the game owner's own words for done) at the top of the list. Then every item answers one question: does this move that line? Progress is measured against those words, never against the model's own plan.
  • Forbid the plausible constant. A value that is not read is ABSENT, with the reason. The iron law is in the rules file because a model, when stuck, will otherwise supply a number that looks right.

Saving tokens: ask the index, read the file last

Anthropic's own guidance names the constraint: the context window fills up fast, and performance degrades as it fills (Best practices for Claude Code, https://code.claude.com/docs/en/best-practices). Every file the model reads to answer a question is context it cannot use for the port. The toolkit holds two indexes that answer such questions instead:

  • The catalogue: py -m u2ue find <words> searches the concepts, verbs, adapters, tools, documents, measured Unity rules, converter stages and routes, and prints each hit as path:line. Its selftest (py -m u2ue find --selftest) checks every source it reads.
  • The game's class model: py -m u2ue --project <game> uml extract, then uml where | ask | callers | tests <Name>. It is built from the game's own code roots, and from its engine-free model once one is scaffolded. A project with no code roots is refused, never pointed at a guessed folder (py -m u2ue.verbs.uml --selftest).

The rule that matters most about any index was measured on the reference port, which also searched a compiler-grade index of the game's Unity assembly. A fresh rebuild, minutes old, held no rows at all for five symbols that had moved into the engine-free model, because it indexed one assembly and the port had moved code out of it on purpose. A miss is UNKNOWN, never ABSENT. Before you trust a miss, check what the index read and when.

The lookup skill (u2ue-lookup) is the order to ask in: the catalogue, then the class model, then a text search for an exact name, then the file - and only the lines named.

Several agents, or one: measured

A common belief: several agents work faster but spend more tokens. It was tested on this toolkit with an exact answer key (u2ue/survey/agent_bench.py). The task is to find where each named function or class is defined. Python's own parser builds the key, so an answer is right or wrong by construction. The same task ran in each condition below, and every run was judged.

The lookup task (seed 1017): 12 names, each to be found where it is defined, the answer key built by Python's own parser over the toolkit's code, every run judged against it by survey/agent_bench.py. One run per condition.

condition agents right tokens tokens a name wall-clock (slowest agent)
one agent, text search 1 12 of 12 90,998 7,583 16 s
one agent, the toolkit's index 1 12 of 12 92,099 7,674 67 s
three agents in parallel, text search 3 12 of 12 271,002 22,583 14 s
three agents in parallel, the index 3 12 of 12 272,270 22,689 37 s
one lean agent (no project rules file), text search 1 12 of 12 48,228 4,019 9 s

What the runs measured:

  • Every condition was right on every name (12 of 12 each): the task was easy for all of them.
  • Three agents cost 3.0 times the tokens of one (text search: 271,002 against 90,998), and the wall-clock moved from 16 s to 14 s.
  • Most of an agent's cost is its starting context: a lean agent that does not load the project's rules file did the same task for 48,228 tokens against 90,998 - 47 % less - before any work differs.
  • The index did not save tokens on exact names (92,099 against 90,998) and was slower (67 s against 16 s): a single text search per unique name is already cheap.

The manual's writers: six writer agents drafting the u2ue manual's new chapters in parallel (2026-10-17, launched 11:3x), each a general-purpose agent with the project's rules file loaded. Source: the agent platform's usage report for each agent (tokens, wall-clock), copied from each agent's completion notice.

writer tokens minutes words written
a1 Shuriken to Niagara 573,684 26 10,786
a2 the Unity tools 482,178 24 7,992
a3 the Unreal tools 477,652 26 6,971
a4 test-driven porting 433,857 24 7,000
a5 folding eight documents in 588,767 39 25,617
a6 prior art (Appendix D) 265,493 12 9,653
  • 2,821,631 tokens for 68,019 words (41 a word); the slowest writer took 39 minutes, the six together 2.5 agent-hours: in parallel the work finished 3.9 times sooner than the same six runs one after another.
  • Not measured: what one agent would have spent doing all six in turn. Its context would have grown with every chapter, so its tokens are not the sum above, and no record says which way that goes.

What this means for a port, read with the caution that each condition ran once:

  • Fan out for big work that splits cleanly, not for small work. The writers' work was large, and each writer owned its own files, so parallel agents bought real time. The lookup task was small, so three agents bought almost none and paid three starting contexts for it.
  • The rules file is a tax every agent pays. The lean agent's saving is the project rules file it did not load. Anthropic's guidance says the same from the other side: keep the rules file short, because a bloated one makes the model ignore the rules that matter. Move what is not needed every time into skills, which load on demand, and give lookups to a lean read-only agent.
  • For exact names, a text search is as good as an index. The index earns its place as a refuser of fabrications, not yet as a token saver: the class-model gate refuses a method name the code lacks (Chapter 14).
  • Not measured yet: questions a text search answers badly, such as who calls a function through an interface, which measured rule applies to an emitter, or which use-case step a verb proves. That is the next task family for the benchmark. Until it is run, the toolkit makes no token claim for the index on such questions.

To run the benchmark on your own machine and your own rules file:

py u2ue/survey/agent_bench.py task --seed <S>
py u2ue/survey/agent_bench.py prompt --seed <S> --slice 1/1 --tools grep
py u2ue/survey/agent_bench.py add --seed <S> --condition one-grep --tokens <N> --ms <M> --answers <file>
py u2ue/survey/agent_bench.py report --seed <S>

Reviewing AI-written code

Anthropic publishes how it reviews work done by Claude (Best practices for Claude Code, the same page). In short:

  • Give the model a check it can run - a test suite, a build, a script that diffs against a fixture, a screenshot to compare. A model stops when the work looks done, and without a check, "looks done" is the only signal.
  • Have it show evidence rather than assert success: the command it ran, and what that command returned.
  • Explore, plan, then code.
  • Review in a fresh context. A reviewer in a separate subagent (an agent another agent starts, with a context of its own) sees only the diff and the criteria, not the reasoning that produced the change. One instance can write the tests and another the code.
  • Scope the reviewer. A reviewer asked to find gaps will report some. Tell it to flag only gaps that affect correctness or the stated requirements.
  • Mind the trust-then-verify gap: a plausible implementation that misses its edge cases. If it cannot be verified, do not ship it.

u2ue builds each of these in, and adds UML at both ends: to steer the work, and to review it.

  1. Checks it can run, everywhere. Every step of a skill written in steps has a RUN: and a DONE WHEN: (the skill gate). Every pillar of the product has recurring checks (py -m u2ue --project <game> cycle), and red stops the cycle.
  2. Checks that can fail. A judge with no plant proves nothing, so every judge has one (py -m u2ue --project <game> judge --prove), and a gate that is widened is re-proven against its plants (Chapter 14).
  3. Evidence, not claims. Every number names its record (u2ue metrics). A task line is ticked with its evidence, never with "done".
  4. Fresh-context reviewers. A reviewer gets the diff and the criteria, never the reasoning that produced the change. Measured while this manual was written: agents held to gates rather than their own word, reading the tools' code with fresh eyes, found defects in the tools themselves - a console check that can miss new errors, a recovery script that acts on every editor on the machine, a field gate blind to a module family. Each finding went onto the task list with its file, instead of being patched quietly.
  5. UML for the prompt. A slice's diagram is drawn before its code moves (the logic skill's step 2). The model is asked to make the diagram true, and the diagram is checked against the code. The toolkit itself was moved under its own concept model the same way (Chapter 22).
  6. UML for the review. A reviewer reads the slice's generated diagram before the diff line by line, and uml check --doc fails a name the diagram or the use cases use and the code lacks, so the model cannot be out of date with the code (Chapter 14). Between sessions, the class model's snapshot and diff (uml snapshot, uml diff) show what changed in structure. Chapter 22 shows the same review applied to the toolkit.
  7. Scoped review. The acceptance sentence sits at the top of the list, and reviews report gaps against it, not style.

A session, start to finish

  1. Find where the port stands. py -m u2ue --project <game> logic names the next step.
  2. Look things up before reading. py -m u2ue find <words>, then py -m u2ue --project <game> uml where <Name>; read only the lines named.
  3. Draw the slice. py -m u2ue --project <game> uml mermaid --focus <TypeA> <TypeB>, then the target diagram the slice must become.
  4. Move the slice and prove it. Move it, then run py -m u2ue --project <game> digest run --entry <Ns.Class.Method> --cases <Cases.cs> and py -m u2ue --project <game> parity until they exit 0.
  5. Check the toolkit and the project. py -m u2ue --project <game> check.
  6. Review in a fresh context. Give a separate agent the diff and the slice's diagram, and ask only for gaps against the acceptance sentence.
  7. Run the cycle before any report. py -m u2ue --project <game> cycle; red stops the session's report, not the session.
  8. Write the evidence onto the list, take the next item, and report only at the end of the run.

16. Troubleshooting

Who this is for: the porting developer whose port has stopped or looks wrong - each symptom, its cause and what to do, with where the full answer is.

Every entry was met on the reference port, so each is a trap your port can meet too. The symptom comes first, then the cause, then what to do. Each section names the procedure step it branches from, so you can return to where you were; an entry that branches from another step names its own.

Finding your problem

Start from what you see; each row names where its answer is.

what you see where the answer is
a command printed REFUSED: ... that verb's refusals, every message with its line, are in Chapter 19; the message names its cause, so fix the input it names and run it again
a command says the project is missing a path or a key py -m u2ue --project <game> info opens every path the project file names; Chapter 3, the project file
a headless Unreal hangs, its log grows without end, or a long build stops half way Unreal runs, below; Chapter 13, headless Unreal runs
Unreal plays sound through the speakers, or records silence Unreal runs, below; Chapter 13, audio
a Niagara system draws nothing in an editor script Unreal runs, below; Chapter 13, editor scripting limits
a managed C# editor wedges, or shows compile errors for code that builds Unreal runs, below; Chapter 13, managed C# in Unreal
the converter writes a value but the effect ignores it Chapter 11, the traps (Unreal's Python API: a failed write returns false)
an emitter is born late, counts differ, or a child never fires Chapter 11, the traps (events, sub-emitters and trails); Chapter 9 for the conformance diff
a texture, a blend or a material looks different though the file is the same Reading Unity files, below; Chapter 11, materials and textures
the YAML reader refuses a prefab or a scene Reading Unity files, below; Chapter 6, prefab YAML
Unity crashes or a probe never runs Measuring in Unity, below; Chapter 12, never disturb the owner
the Unity bridge stops answering, or an editor sits behind a modal dialog Chapter 12, recovery
two agents trample one editor Chapter 12, several agents at once
a float or a printed number differs between Unity and the port Comparing runtimes, below; Chapter 14, determinism across runtimes
a patch script left a file empty, or two patches fight Writing tools, below
a gate says something is ABSENT that you know exists, or a test is red in a file someone else just wrote Gates and reports, below; Chapter 14, rules that keep tests honest
a photo differs from Unity's but the numbers agree Gates and reports, below; Chapter 11, proof
u2ue metrics prints STALE or ABSENT Gates and reports, below; Chapter 10

Unreal runs

Branches from Chapter 4, step 7.

A headless Unreal never finishes and its log grows to hundreds of megabytes. UnrealSharp finds dotnet by the PATH entry Program Files\dotnet\ with the trailing backslash. Git Bash hands PowerShell a PATH without it, so UnrealSharp reports ".NET SDK can't be found" and, under -unattended, raises the dialog again forever (measured: a 634 MB log, nothing built). Run every Unreal verb from native PowerShell. The verbs refuse up front when they are launched from Git Bash.

A long build stops at exactly the shell tool's timeout, leaving the content half old and half new. Stopping a background task kills its children, including UnrealEditor-Cmd. Before a long launch, compare the tool's timeout with the script's own watchdog and give the tool the larger one.

Two Unreal runs at once. One headless Unreal at a time. Every verb that starts Unreal (build, read, photo, scene, host) asks the adapter's host_busy and refuses while an Unreal, or a build queue the game's adapter names, holds the host. --dry on build, read, photo or scene shows the host's state.

Niagara draws nothing in an editor script. -run=pythonscript asserts, and -ExecutePythonScript quits before the tick loop runs. The editor world never ticks actors, so Niagara simulates only inside Simulate or Play-In-Editor unless something advances it. The read-back advances each system itself: NiagaraSimCacheFunctionLibrary's immediate capture with bAdvanceSimulation (effects_tools/u1e_color_size_readback.py, which u2ue read runs).

A headless run plays sound through the user's speakers, or records silence. Pass -DeterministicAudio (the non-realtime renderer: nothing reaches a device, and each tick renders its own delta) and -ini:Engine:[Audio]:UnfocusedVolumeMultiplier=1.0 (an unfocused application otherwise mixes at volume 0).

An UnrealSharp editor wedges while files are being generated. With automatic hot reload on, the editor recompiles a managed file the instant it is written, mid-write, fails, and can stop responding. Set AutomaticHotReloading=Off in the host's DefaultEditorPerProjectUserSettings.ini, or keep the editor closed while a tool writes managed C#.

Reading Unity files

Branches from Chapter 4, step 5.

The reader refuses a scene with m_AddedGameObjects or m_AddedComponents. A prefab instance that adds an object or a component to its source prefab is not ported yet, and the nested-prefab expander refuses it by name. Removals are applied: m_RemovedComponents and m_RemovedGameObjects take the component, or the object with its child subtree, out of the instance. u2ue data --no-expand reads the scene's own components without expanding instances. Branches from Chapter 4, step 4.

A nested prefab's object cannot be found by its fileID. A nested object's id is the instance's id XOR the source object's id, with the top bit cleared.

A material's values look like its shader's defaults. A material variant stores only what it overrides; the rest comes through m_Parent. Read the chain.

An effect's blend mode is wrong. The blend mode is a number in the material (_DstBlend == 1 is additive), never the shader's name.

A texture looks different in Unreal although the file is the same. Unity samples its imported texture (mip chain, alpha fill, size caps), not the source file. The import is in Library/Artifacts and can be read offline (effects_tools/unity_tex_artifact.py); validate the match against the source, since the artifact index can point at a neighbouring asset. Branches from Chapter 4, step 7.

Measuring in Unity

Branches from Chapter 8, step 7.

Unity crashes in native code during a probe. ParticleSystem.Particle.GetMeshIndex on a renderer that is not a Mesh renderer with meshes kills the editor; a managed try/catch does not see it. Check the renderer before any renderer-dependent query, and write the field ABSENT otherwise.

A probe's work never runs while the editor is in the background. EditorApplication.delayCall does not fire for an unfocused editor. Poll from EditorApplication.update.

The first case a probe renders is wrong, and only that one. The first render after a probe sets up its scene can come out incomplete (measured: without the scene's ambient, so an ON - OFF difference read the ambient as light). Throw one or two renders away before the first case, and have the judge compare every OFF render of a surface against the others, so an incomplete one is refused by name instead of read as data.

A measurement right after a recompile reproduces the old numbers. Entering Play while a compile is pending runs the old assembly. Wait until the editor assembly's timestamp is newer than the source and isCompiling reads false, then Play. Branches from Chapter 8, step 6.

Comparing runtimes

Branches from Chapter 5, step 7.

Text built from floats differs between Unity and .NET. Unity's Mono rounds float text to seven significant digits first, rounds halves away from zero, and prints a value that rounds to zero without a sign. Any number a player reads, or a stream compared against Unity, goes through one formatter that reproduces Mono's rules.

Float results differ by one ULP. Mono may keep a float expression at higher precision. u2ue parity names every such row; an allowance pins the exact row and bits, and the fix (explicit float locals) moves Unity's own value, so it is the owner's call. Chapter 14 has what the standards allow and the two differences that are not rounding.

System.Text.Json writes {} for a Unity data class. Unity's JsonUtility serializes public fields; System.Text.Json ignores fields unless IncludeFields = true.

Writing tools

Branches from Chapter 18, A converter route, step 2.

A patch that refused left the file it patches empty. A patch script changes a tool's source by finding an anchor (an exact piece of its text) and replacing it. open(path, "w").write(patch(text)) opens - and truncates - the file before patch runs, so when patch refuses (an anchor moved, already patched) the file is left at 0 bytes. Build the new text first, then open the file. Give the patch a plant too: pointed at a copy that already carries its mark, it must refuse and leave the copy byte-identical.

Two patches to one file, each proven on its own copy. That proves each, not both: an anchor the first one moves would make the second refuse at landing time (when it is applied to the live file). Apply them in landing order to one copy and compile it before either lands; when the order is not fixed, prove both orders.

Gates and reports

Branches from Chapter 4, step 6.

A gate reports a symbol ABSENT that you know exists. Check whether the port moved it (into the model, for example) before believing the gate. Widen the gate to follow the move, then re-run its plants.

The photo of an effect differs from Unity's in a way the data does not. A photo is one draw of a random process, and a frame can catch a capture artefact. u2ue metrics counts the flagged frames labelled RANDDRAW (one draw) or GRIDTICK apart, as the capture's difference, not the port's. Compare several frames and the read-back data before calling a route wrong. Branches from Chapter 4, step 7.

u2ue metrics prints STALE. An input is older than the newest build. Re-run the step that writes it (the read-back sweep, the photo pass); the number is never presented as current until then. ABSENT means the record a number needs is not on disk, and names it. Branches from Chapter 4, step 8.

Questions and answers

Who this is for: the porting developer - short answers to the questions asked before and during a port, and the reasons behind the toolkit's design, each with the chapter that has the detail.

The first two sections answer what a porter asks before and during a port. The rest give the reasons for the toolkit's design, most of them answers to "why didn't you just...".

Before you start

What do I need installed? Windows 11 with native PowerShell for the Unreal runs, Python 3.13 with PyYAML, the .NET SDK 8 or later, Unreal Engine 5.7, and the game's own Unity Editor for measurement windows and reference photos. The full table, with what needs each, is in Chapter 3.

Does my Unity project have to be set up in a particular way? One setting: asset serialization must be Force Text, so prefabs, scenes, materials and .meta files are YAML the toolkit can read. The toolkit reads the project and writes nothing into it. The one exception is a measurement window: it drops its probe files into the project for the run, removes them after, and never replaces a file (Chapter 8; "Measuring Unity", below).

Does the Unity Editor have to be open? No, for almost everything. Reading prefabs, scenes, materials and data, the inventory, the extraction, the Unreal build, parity and Unity's own Mono runtime all run with no editor. An editor is needed only to measure a behaviour (a window), to take Unity's reference photos, to export a scene and to capture a UI screen (Chapter 12).

Which Unity and Unreal versions does it work with? It was built on Unity 6000.3 with Unreal Engine 5.7, and exercised on a second game on Unity 2021.3. Every measured rule records the Unity version it was measured on. On any other version, u2ue check names the rule as UNVERIFIED: the build still uses it, but no report calls it measured. Re-measuring is the owner's decision; the probes and judges are the means (Chapter 8).

Do I need an AI model to use it? No. Every verb is a command a person can run. The package's skills are written so that an AI model can do the porter's work step by step and have each step checked (Chapter 5, Chapter 15).

What does it not port? Animation and physics are not covered (Chapter 6, Appendix B). On the effects side, VFX Graph assets and particle systems authored directly in scenes are not covered either, and the extraction lists them with their counts (Chapter 4, step 5).

Can I port only the effects? Yes. Part one of the tutorial (Chapter 4) takes a game's effects to a first report with no code port at all. The logic, the scenes and the UI are separate procedures you can run later, or never.

During a port

Where do the results go? Into the work folders your project file names (work.effects, work.records and the rest): the IR, the build records, the read-backs, the photos and the reports. Nothing is written into the Unity project (Chapter 3).

Can I run several things at once? Headless work, yes. Unreal, no: one headless Unreal at a time, and the verbs that need it refuse while it is busy (Chapter 13). A live Unity Editor has one driver at a time, and the other agents work headless or on a second editor instance (Chapter 12).

How do I know the port is right? Four numbers, never one combined figure: coverage (does it draw), measured (drawn by a measured rule), data (do its particles follow Unity's numbers) and image (do the frames agree, with capture artefacts labelled and counted apart). u2ue metrics prints each with its denominator (Chapter 10). u2ue conform holds every emitter to Unity's own particle state (Chapter 9), and u2ue parity holds the game's rules to every runtime by float bits (Chapter 14).

What happens when the toolkit cannot read or convert something? It says so. A value that cannot be read is ABSENT, with the reason. An effect the reader cannot follow is REFUSED by key. An emitter the converter cannot port carries its named gap on the acceptance page. Nothing is dropped silently, and nothing is replaced by a plausible default (Chapter 1, Chapter 7).

My game chooses its effects in code, not by placing prefabs. What then? Write an adapter. It answers the few questions that depend on a game, and the first of them is which effects the game fires (effect_keys()). Chapter 18 has the recipe.

A gate went red, but I know the code is right. First check whether the code moved. A gate that walks one folder reports a symbol it cannot see as absent. Widen the gate to follow the move, then prove that it can still fail (Chapter 14, Chapter 16). Never re-record a baseline to make a red gate green.

How long does a port take? Before you start, py -m u2ue estimate --unity <project> says what the port will cost in tokens, with no editor and no project file. It gives no time, because no time per line has been measured yet (What a port costs). During the port the toolkit measures time rather than estimating it: u2ue tempo times each converter route from its first code to its verified flip, read off git, and u2ue metrics reports the machine time of the builds (Chapter 10). For scale, measured on the reference port (2026-10-15): building 673 effect keys took 31.8 hours of headless machine time, summed over the keys, a median of 98 s a key (Appendix A).

After the port

The game keeps changing in Unity. How does the port keep up? It depends on what changed. The logic lives in one engine-free model that Unity and Unreal both run (Chapter 5), so a rule changes once, in the model, and u2ue parity proves the engines still agree bit for bit. Content authored in Unity is ported again by the verb for that part: u2ue scene for a level, checked against that scene's own baseline (Chapter 6); u2ue extract and u2ue build for effects (Chapter 7); u2ue ui convert for screens (Chapter 6). Running u2ue port again re-reads every stage from its records (Chapter 4). What is not built yet is a step that finds which assets changed since the last port: after a change, rerun the verb for that part yourself.

After the port, is Unity or Unreal the source? That is the owner's decision, and the toolkit does not make it. The verbs read the Unity project, so they serve a team that keeps authoring levels, effects and screens in Unity and ports them again. A team that moves its authoring into Unreal stops porting content; the shared model still keeps the rules in one place for both engines, for as long as both ship.

The approach

Why not just translate the MonoBehaviours into Actors? Because then nothing can be compared. Two engines running two hand-translated copies of the rules disagree in ways no one can locate: every difference is an argument. Moving the rules into one engine-free model, run by both engines, turns every difference into a row in a digest that u2ue parity compares bit for bit (Chapter 5). It is also less code: the hosts are thin, and the rules are written once.

Why doesn't a verb move the game's code for me? Because where the seams go is a design decision about your game, and a tool that guessed them would produce a model nobody chose. The logic skill has the porter, or an AI model, make that decision one slice at a time (Chapter 5), and the toolkit does everything around it: the inventory says what each type touches, the runtime library gives the moved code Unity's rules, the gates keep the model engine-free, parity proves the result.

Why is there no off-the-shelf Shuriken to Niagara converter in here? There is not one to use. Unreal ships a converter from Cascade, its own legacy particle system, to Niagara, and the toolkit uses its library (FXConverterUtilitiesLibrary) to write Niagara stacks, but what to write - Shuriken's semantics, module by module - is the toolkit's own work, measured against Unity where Unity does not document it (Chapter 11).

Why read Unity's YAML instead of exporting through the Unity editor? Reading text needs no editor, so it runs on any machine, in any order, as often as wanted, and leaves the game owner's editor alone. It is deterministic and diffable. The editor is used only for what cannot be read from files: measuring behaviour, and reference photos. The price is that the project must be serialized as text, and that every corner of the format must be handled - which is why an unhandled case is refused by name rather than half-read.

Why Python for the tools, and C# for the runtime? The converter has to run inside Unreal's editor, whose scripting language is Python, so the readers and the converter share one language and one set of tests. The runtime library is C# because it ships into the game, beside the game's own C#.

Measuring Unity

Why measure Unity at all? Read the documentation. The documentation does not say most of what a port must reproduce: the frame a sub-emitter's particle is born in, the order a mesh particle's rotation and a non-uniform scale apply in, how a TrailRenderer drops its points, what a Timeline does before a clip starts. Unity's native engine code is not public, so where the documentation is silent, the behaviour is measured.

Why write the judge before the measurement? A judge written after the data is fitted to the data and passes whatever Unity happened to do. Written first, with planted wrong answers it must refuse, it can be wrong in a way the measurement exposes - which is the point (Chapter 8 has a bake the judge refused, and what it taught).

Why run probes in the owner's own editor, and only after ten idle minutes? Because a second Unity editor on the same machine was measured to take the owner's machine away: it steals window focus on every assembly reload and saturates the processor for many minutes. A probe needs a real compile and sometimes Play mode, which interrupts whoever is working. So a window waits for ten minutes without a key or a mouse movement, stops at its next step when the owner returns, and never answers a modal dialog. A dedicated measurement machine is the better setup when there is one; the protocol is the same.

Why are the probes temporary files dropped into the project, not a permanent editor package? So the game's project carries nothing it did not ask for. The release is to ship them as the package's Editor assembly (Appendix B): the same code, installed once, by the project owner's decision.

Converting and building

Why is every new behaviour behind a switch that defaults to off? Because a converter change that is wrong silently changes hundreds of effects. Behind a switch, the change is proven to alter nothing while off (whole_trace replays the converter over every emitter), then to alter exactly the emitters it names while on, then trialled, read back, photographed and looked at - and only then flipped, with an evidence row. Every switch that reads ON in Chapter 21's table was flipped that way, and the table counts its evidence rows. The cost is the number of switches, which is why retiring the permanently-on ones is on the roadmap (Appendix B).

Why are changes written as patch scripts that land after the build? A full rebuild runs for many hours and loads the converter afresh for each chunk of effects. Editing the converter mid-build would make the build two builds, half old and half new, and its numbers would describe neither. So a change to the live tree is proven on a copy (--prove) and applied (--land) when the build ends; the landing step refuses when an anchor moved or the file already carries the patch. u2ue trial avoids the problem another way: it runs from a snapshot of the code, so an edit to the live converter cannot change a trial that is already running (Chapter 20).

Why only one Unreal process at a time? Two engines contend for memory, the derived-data cache and the project's packages, and an open editor locks packages another process needs to save. So a verb that needs Unreal refuses while another holds the host, naming what holds it, instead of racing it (Chapter 13).

Why headless Unreal, and not a running editor? A headless run is reproducible, unattended and owns nothing anyone else is using. The cost is that the editor world does not tick actors, so Niagara does not simulate by itself; the read-back advances each system explicitly (Chapter 13).

Why does the YAML reader refuse a scene that edits an object inside a model? A model (an FBX) is binary, so the scene's YAML holds only the edit, not the object it edits. Reading FBX in Python to rebuild that object's transform would re-derive what Unity has already resolved: the scene's glTF export walks Unity's live hierarchy and writes every node's own transform, model nodes included. So such a scene is refused by name on the YAML route, and u2ue shear --gltf and u2ue scene read the export instead.

Why one-ULP differences? Surely nobody can see them. Nobody can see them, but a turn-based game can feel them: a damage value one unit in the last place lower can leave a unit alive that should have died. The toolkit pins each such row to its exact bits and reports which runtime is the odd one out, and leaves the fix - which moves the shipped game's own numbers - to the owner (Chapter 14).

Rendering, lighting and UI

Why do lit effects compute Unity's lighting inside the Unreal material instead of using Unreal's lights? Because the goal is Unity's look, and URP and Unreal light a surface differently: a different BRDF, a different ambient (URP's spherical harmonics), a different reflection decode. Evaluating URP's own Lit, transcribed from its source, with the scene's measured sun, ambient and reflection cube, reproduces Unity's result. The trade-off is named: those materials follow the lighting that was measured, not lighting that changes at run time, and they draw no fog or shadows (Chapter 7).

Why is a Unity point light of intensity 1 an Unreal light of pi candelas? Read from both engines' source: URP's diffuse term has no 1 / pi and Unreal's Lambert does, and Unreal's candela unit is 1e4 internal units per candela at 100 cm per metre. pi x I candelas makes the two equal. The Unity side was measured on lit pixels to confirm the formula; the remaining 4 % (URP's diffuse carries a 0.96 that Unreal's does not) is measured and named, not hidden.

Why is the UI painted in one widget instead of built as UMG? Two measured reasons. uGUI's layout (anchors, layout groups, TextMeshPro's glyph placement) does not map onto UMG's, so a UMG rebuild lays out differently; a port of uGUI's own solver lays out as Unity does, and its tests hold it to Unity's captures. And from C#, UnrealSharp exposes a widget tree's root as read-only, so a UMG tree cannot be assembled from the game's code at all.

Why does Unity's reference photo of an effect have no lights? Most effects are unlit and additive: lights do not change them, and an empty scene makes the frame comparable. For lit materials the photo probe has a lit mode that opens the scene and copies its sun, because a lit material photographed in the dark compares nothing.

Why are the Unreal hosts C# and not Blueprints or C++? The game's code is C#. With UnrealSharp the moved model runs unchanged in Unreal, and the host is a thin C# layer. C++ is used only where the managed bindings do not reach (handing raw PCM to Unreal's mixer).

Numbers and reports

Why does every number come with a denominator and a date? Because a percentage without them cannot be checked or compared, and an old number quoted as current is how a project believes it is further along than it is. A coverage figure is quoted as N of the M emitters Unity draws, on <date>: the reader can then find the records it came from, and see when they are older than the newest build.

Why print STALE or ABSENT instead of the last known value? A last known value describes builds that no longer exist. Printing it would be a substitute, which is the one thing the toolkit does not do anywhere.

Why isn't an effect Unity does not draw counted as a gap? Because porting it would make Unreal draw something Unity does not. On the reference port, the first acceptance pages charged 348 such emitters as gaps; each is now classified by a rule (never fired, never started, draws nothing in Unity), and only what Unity draws and Unreal does not is a gap.

Why look at the pictures if the numbers pass? Numbers and pictures fail differently. One render where the whole scene went black scored better on a pixel metric, because dark geometry stopped hiding a bright backdrop. The data proves itself first; then the numbers and the pictures confirm it, and a picture counts only once someone has opened it (Chapter 9).

17. Use cases

Who this is for: the toolkit developer and the reviewer - every use case of u2ue, step by step, each step cited to the page it was read from and to the command that proves it. After it you can follow any step of a port back to its source and its check.

This chapter is the toolkit's requirements model: what each kind of user does with it, step by step. It is generated, not written: it is read from the toolkit's own documents (the procedures of this manual, the toolkit's skills, the stakeholder requirements in u2ue/USECASES.md, the verb registry, and the pillars in u2ue/pillars.py), each procedure chained into a use case and every step cited to the page it was read from. When a page changes, the model changes with it, and a step with no source is printed as INFERRED, a requirement nobody wrote (Reading UML and use cases, "The chain").

How to read a use case

Reading UML and use cases explains the form and its fields; what follows is how this chapter applies it.

  • The level follows Cockburn: kite is a summary goal that spans many sittings (the epic), sea is one user goal achieved in one sitting (most cases), fish is a sub-function.
  • Fully dressed: each case states its primary actor, its trigger, its scope, the precondition that must hold before it starts, the minimal guarantee that holds even when it fails, and the success guarantee that holds when it succeeds.
  • The main success scenario is three to eleven steps. Each step's postcondition (what it leaves true) is the next step's precondition, so a step that needs what nothing before it guarantees shows a gap.
  • Extensions are where the chain breaks. Each is numbered by the step it branches from (3a branches from step 3; * from any step), and each one was read where its document says it starts. Chapter 16 is part of the model, not a page beside it.
  • Include and extend point opposite ways. An include runs from the base case to the case it includes (the epic includes the quick start). An extend runs from the extension to the base it extends.
  • Proven by names the command that checks a step. That command is the test, and it must fail on a planted defect before it is trusted (Chapter 14).

22 use cases - one summary-level epic and 21 user-goal cases - with 143 steps and 41 extensions, every step read from the page named beside it.

The actors

actor who use cases
developer extending the toolkit UC-01, UC-02, UC-03, UC-04, UC-05, UC-06, UC-09
opus the AI model UC-11, UC-13, UC-14, UC-16, UC-20
owner whose product it is UC-07, UC-19
porter porting a game UC-08, EPIC-1, UC-12, UC-15, UC-17, UC-18, UC-21
toolkit its own runners UC-10

The use case diagram

Mermaid has no use case diagram, so this is a flowchart drawn as one: the actors stand outside the system boundary, each oval is a case, a dashed arrow from the epic is an include (base to included) and a dashed arrow into the epic is an extend (extension to base) - the two point opposite ways.

flowchart LR
    A_developer["developer<br/><i>extending the toolkit</i>"]:::actor
    A_opus["opus<br/><i>the AI model</i>"]:::actor
    A_owner["owner<br/><i>whose product it is</i>"]:::actor
    A_porter["porter<br/><i>porting a game</i>"]:::actor
    A_toolkit["toolkit<br/><i>its own runners</i>"]:::actor
    subgraph SYS["u2ue - the system boundary"]
        UC01(["UC-01<br/>A developer lands a<br/>converter route behind a<br/>switch"])
        UC02(["UC-02<br/>A developer answers one<br/>game-specific question<br/>with an adapter"])
        UC03(["UC-03<br/>A developer ports a Unity<br/>shader's material family"])
        UC04(["UC-04<br/>A developer makes the<br/>converter read a rule<br/>measured in Unity"])
        UC05(["UC-05<br/>A developer gives a tool a<br/>selftest the check runs"])
        UC06(["UC-06<br/>A developer adds a verb to<br/>the facade"])
        UC07(["UC-07<br/>The owner checks every<br/>pillar of the product each<br/>cycle"])
        UC08(["UC-08<br/>The porter holds every key<br/>of a build to Unity on<br/>numbers"])
        UC09(["UC-09<br/>A developer moves a tool<br/>onto the project file"])
        EPIC1(["EPIC-1<br/>Port a Unity game to<br/>Unreal and show how<br/>identical it is"])
        UC10(["UC-10<br/>The toolkit measures a<br/>Unity behaviour in the<br/>owner's idle editor"])
        UC11(["UC-11<br/>Prove it before reporting<br/>it"])
        UC12(["UC-12<br/>The porter imports a Unity<br/>scene as an Unreal level<br/>and grades it"])
        UC13(["UC-13<br/>Opus ports one effect gap<br/>by the route protocol"])
        UC14(["UC-14<br/>Record the slice and take<br/>the next"])
        UC15(["UC-15<br/>The porter moves a game's<br/>code into an engine-free<br/>model"])
        UC16(["UC-16<br/>Record the slice and take<br/>the next one"])
        UC17(["UC-17<br/>The porter lays out the<br/>game's uGUI screens in<br/>Unreal"])
        UC18(["UC-18<br/>The porter takes a new<br/>game from its project file<br/>to its first report"])
        UC19(["UC-19<br/>The owner assembles the<br/>toolkit's repository from<br/>its own trees"])
        UC20(["UC-20<br/>Opus runs the effect<br/>pipeline from the prefabs<br/>to the metrics"])
        UC21(["UC-21<br/>The porter verifies the<br/>toolkit on their machine"])
    end
    A_developer --- UC01
    A_developer --- UC02
    A_developer --- UC03
    A_developer --- UC04
    A_developer --- UC05
    A_developer --- UC06
    A_owner --- UC07
    A_porter --- UC08
    A_developer --- UC09
    A_porter --- EPIC1
    A_toolkit --- UC10
    A_opus --- UC11
    A_porter --- UC12
    A_opus --- UC13
    A_opus --- UC14
    A_porter --- UC15
    A_opus --- UC16
    A_porter --- UC17
    A_porter --- UC18
    A_owner --- UC19
    A_opus --- UC20
    A_porter --- UC21
    UC02 -.->|"extend (at 3a)"| EPIC1
    EPIC1 -.->|"include (step 8)"| UC07
    UC10 -.->|"extend (at 7a)"| EPIC1
    EPIC1 -.->|"include (step 2, 3, 4, 5, 6, 7, 8, 9)"| UC11
    EPIC1 -.->|"include (step 6)"| UC12
    EPIC1 -.->|"include (step 7)"| UC13
    EPIC1 -.->|"include (step 3, 4, 5, 6)"| UC15
    EPIC1 -.->|"include (step 3, 4, 5, 8)"| UC16
    EPIC1 -.->|"include (step 5)"| UC17
    EPIC1 -.->|"include (step 2, 3, 7, 8)"| UC18
    EPIC1 -.->|"include (step 7)"| UC20
    classDef actor fill:none,stroke-dasharray:3 3

EPIC-1 Port a Unity game to Unreal and show how identical it is

The epic is the table of contents of a port: each step names the use case that carries it.

flowchart TD
    START(("start"))
    S1["1. The porter finds what the toolkit holds<br/>for their question"]
    START --> S1
    S2["2. The porter describes the project: Unity<br/>root and version, the Unreal project,<br/>the work folder, the adapter"]
    S1 --> S2
    S3["3. The tool inventories the game: every<br/>MonoBehaviour, the Unity APIs it calls,<br/>the scenes and prefabs, the effects"]
    S2 --> S3
    S4["4. The porter (or Opus, through the<br/>u2ue-logic skill) moves the rules out of<br/>the MonoBehaviours into an engine-free<br/>model, behind a platform seam and a view<br/>seam"]
    S3 --> S4
    S5["5. The porter implements the Unreal<br/>adapters for those seams: view, input,<br/>camera, effects player, platform<br/>services"]
    S4 --> S5
    S6["6. The tool converts the transform chain<br/>and the scenes: axes, units, rotation<br/>order, scale, hierarchy"]
    S5 --> S6
    S7["7. The tool ports the effects"]
    S6 --> S7
    S8["8. The tool proves parity and reports it"]
    S7 --> S8
    S9["9. The game owner answers the decisions the<br/>page asks, and only theirs"]
    S8 --> S9
    DONE(("the game runs on Unreal<br/>and every gap is named"))
    S9 --> DONE
    X3a{{"3a The game's effects are chosen by its<br/>code, not by its prefabs"}}
    S3 -.-> X3a
    X4a{{"4a A MonoBehaviour WAITS (coroutines,<br/>Invoke, yield)"}}
    S4 -.-> X4a
    X6a{{"6a A node has a non-uniform scale under<br/>a rotation"}}
    S6 -.-> X6a
    X7a{{"7a A rule the conversion needs is not<br/>measured"}}
    S7 -.-> X7a
    X8a{{"8a The project's Unity version differs<br/>from the one the rules were measured<br/>on"}}
    S8 -.-> X8a
    X8b{{"8b A frame differs only because one<br/>engine drew one random sample"}}
    S8 -.-> X8b
field
Level kite (summary)
Primary actor porter - porting a game
Trigger a studio decides to move a Unity game to Unreal
Scope u2ue and the porter's two projects.
Precondition the Unity project is on disk serialized as text (YAML prefabs, .meta files); an Unreal project to build into.
Stakeholders the porter wants it to run and to look the same; the game owner wants every difference named and only their decisions asked; a reviewer wants the method to make sense (Q7).
Minimal guarantee everything not ported is NAMED with its reason - never dropped, never stood in for silently (Q11).
Success guarantee the game runs on Unreal from the same rules; the page says, per effect and per system, what draws as Unity draws it, and the numbers (identical, speed) come from records (Q4).
Read from u2ue/USECASES.md

Main success scenario (each step's postcondition is the next step's precondition):

  1. The porter finds what the toolkit holds for their question (u2ue/USECASES.md)
  2. The porter describes the project: Unity root and version, the Unreal project, the work folder, the adapter (u2ue/USECASES.md)
    • carried by UC-11, UC-18
  3. The tool inventories the game: every MonoBehaviour, the Unity APIs it calls, the scenes and prefabs, the effects (u2ue/USECASES.md)
    • carried by UC-11, UC-18, UC-15, UC-16
  4. The porter (or Opus, through the u2ue-logic skill) moves the rules out of the MonoBehaviours into an engine-free model, behind a platform seam and a view seam (u2ue/USECASES.md)
    • carried by UC-11, UC-15, UC-16
  5. The porter implements the Unreal adapters for those seams: view, input, camera, effects player, platform services (u2ue/USECASES.md)
    • carried by UC-11, UC-15, UC-16, UC-17
  6. The tool converts the transform chain and the scenes: axes, units, rotation order, scale, hierarchy (u2ue/USECASES.md)
    • carried by UC-11, UC-15, UC-12
  7. The tool ports the effects (u2ue/USECASES.md)
    • carried by UC-11, UC-18, UC-13, UC-20
  8. The tool proves parity and reports it (u2ue/USECASES.md)
    • carried by UC-11, UC-18, UC-16, UC-07
  9. The game owner answers the decisions the page asks, and only theirs (u2ue/USECASES.md)
    • carried by UC-11

Extensions (where the chain breaks, numbered by the step they branch from):

  • 3a The game's effects are chosen by its code, not by its prefabs - the porter writes an adapter that overrides effect_keys() (u2ue/USECASES.md)
  • 4a A MonoBehaviour WAITS (coroutines, Invoke, yield) - the model never waits; the wait becomes a turn / tick step. Stated (u2ue/USECASES.md)
  • 6a A node has a non-uniform scale under a rotation - Unity draws a shear Unreal's transform cannot hold; it must be refused and (u2ue/USECASES.md)
  • 7a A rule the conversion needs is not measured - UC-8 extends here. (u2ue/USECASES.md)
  • 8a The project's Unity version differs from the one the rules were measured on - versions() names them unverified (HAVE). (u2ue/USECASES.md)
  • 8b A frame differs only because one engine drew one random sample - labelled, never counted (HAVE: the RANDDRAW census). (u2ue/USECASES.md)

UC-01 A developer lands a converter route behind a switch

field
Level sea (user goal)
Primary actor developer - extending the toolkit
Trigger the acceptance page names a gap no route ports
Scope one Unity behaviour the converter did not port before (Chapter 7).
Precondition the behaviour is measured or read.
Minimal guarantee until the route is flipped, it changes no call the converter makes.
Success guarantee the route is on by default, with its evidence in the flip table.
Read from Chapter 18

Main success scenario (each step's postcondition is the next step's precondition):

  1. Measure or read the behaviour (Chapter 8). (Chapter 18)
  2. Write the route behind VFXPORT_, read default OFF. (Chapter 18)
  3. Prove it offline with whole_trace.py: off, identical calls everywhere; on, exactly the predicted emitters change. (Chapter 18)
  4. Trial it (Chapter 18)
  5. Flip it (Chapter 18)

Extensions (where the chain breaks, numbered by the step they branch from):

  • 2a A patch that refused left the file it patches empty - open(path, "w").write(patch(text)) opens - and truncates - the file before patch runs, so when patch refuses (an anchor moved, already patched) the file is left at 0 bytes. Build the new text first, then open the file. Give the patch a plant too: pointed at a copy that already carries its mark, it must refuse and leave the copy byte-identical. (Chapter 16)
  • 2b Two patches to one file, each proven on its own copy - That proves each, not both: an anchor the first one moves would make the second refuse at landing time (when it is applied to the live file). Apply them in landing order to one copy and compile it before either lands; when the order is not fixed, prove both orders. (Chapter 16)

UC-02 A developer answers one game-specific question with an adapter

field
Level sea (user goal)
Primary actor developer - extending the toolkit
Trigger a default answer is wrong for the game
Scope one game-specific answer the default adapter gets wrong.
Precondition a project file that info opens.
Minimal guarantee a question the adapter does not override keeps Unity's own answer.
Success guarantee info names the adapter it loaded, and extract holds the key list to the adapter's spawn rules.
Extends EPIC-1 at 3a
Read from Chapter 18

Main success scenario (each step's postcondition is the next step's precondition):

  1. Find the question (Chapter 18)
  2. Write the adapter (Chapter 18)
  3. Name it (Chapter 18)
    • uses adapter
  4. See it load (Chapter 18)
    • proven by py -m u2ue --project <game> info
  5. See it hold (Chapter 18)
    • proven by py -m u2ue --project <game> extract

UC-03 A developer ports a Unity shader's material family

field
Level sea (user goal)
Primary actor developer - extending the toolkit
Trigger an effect material's shader has no Unreal parent
Scope one Unity shader and every material that uses it.
Precondition the shader's .shadergraph can be read.
Minimal guarantee every surface the shader exposes is accounted for; none is dropped silently.
Success guarantee every material of the family is an instance of one authored parent, its values read from its .mat.
Read from Chapter 18

Main success scenario (each step's postcondition is the next step's precondition):

  1. Author the parent by a script, never by hand (the reference port's vm1_author.py, for its largest family, a vendor's uber shader graph: one Shader Graph whose many features are switched by its keywords and properties). (Chapter 18)
  2. Account for every surface (Chapter 18)
  3. Instance it (Chapter 18)

UC-04 A developer makes the converter read a rule measured in Unity

field
Level sea (user goal)
Primary actor developer - extending the toolkit
Trigger the converter needs a rule Unity's files do not state
Scope one rule the converter uses, measured in Unity.
Precondition the rule cannot be read from Unity's data or its source.
Minimal guarantee a bake the judge cannot read the rule from is refused, with its numbers.
Success guarantee the converter re-derives the rule from the fact file at every build.
Read from Chapter 18

Main success scenario (each step's postcondition is the next step's precondition):

  1. Write the judge first, with planted wrong answers it must refuse (Chapter 8). (Chapter 18)
  2. Write the probe (Chapter 18)
  3. Run it in a window (Chapter 18)
    • proven by py -m u2ue --project <game> window run <spec.json>
  4. Keep the fact file the judge reads off the bake, with the Unity version it was measured on. (Chapter 18)
  5. Re-derive it at build time (Chapter 18)

UC-05 A developer gives a tool a selftest the check runs

field
Level sea (user goal)
Primary actor developer - extending the toolkit
Trigger a tool that can be wrong is written
Scope one tool that can be wrong.
Precondition the tool runs offline, or the reason it cannot is measured.
Minimal guarantee a tool whose selftest cannot run offline is listed with that reason, never skipped silently.
Success guarantee u2ue check runs the selftest and Chapter 21 lists it.
Read from Chapter 18

Main success scenario (each step's postcondition is the next step's precondition):

  1. Plant the defects (Chapter 18)
  2. Register it in u2ue/survey/pt1_selftests.py (RUNS: the tool, its folder, its exact command). (Chapter 18)
  3. Run it with the rest (Chapter 18)
    • proven by py -m u2ue --project <game> check --only selftests
  4. See it listed (Chapter 18)
    • proven by py u2ue/manual/build.py

UC-06 A developer adds a verb to the facade

field
Level sea (user goal)
Primary actor developer - extending the toolkit
Trigger a step of a port has no command
Scope one command of the facade.
Precondition the work it runs exists as a module or a tool on disk.
Minimal guarantee a verb that wraps a tool which is not on disk stops, by name; it never skips.
Success guarantee the command line, find and Chapter 20 all show the verb, from its one registry row.
Read from Chapter 18

Main success scenario (each step's postcondition is the next step's precondition):

  1. Write the module (Chapter 18)
  2. Register it (Chapter 18)
  3. Find it (Chapter 18)
    • proven by py -m u2ue find <name>
  4. Rebuild the manual (Chapter 18)
    • proven by py u2ue/manual/build.py
    • proven by py u2ue/manual/build.py --check

UC-07 The owner checks every pillar of the product each cycle

field
Level sea (user goal)
Primary actor owner - whose product it is
Trigger a work cycle ends, or a report is about to be written
Scope the product - every promise u2ue makes.
Precondition a project file to check the toolkit against.
Minimal guarantee a promise with no check reads ABSENT, never PASS; a failure is FAIL unless a recorded decision explains it.
Success guarantee every pillar PASS, or HELD by a named decision of the owner's.
Included by EPIC-1, step 8
Read from u2ue/pillars.py

Main success scenario (each step's postcondition is the next step's precondition):

  1. pillar 1 auto-port: every asset family that is not logic ports with no human step (u2ue/pillars.py)
    • proven by py -m u2ue --project <game> cycle --pillar 1
  2. pillar 2 ai logic port: Opus, pointed at a game through the skill, ports its logic (u2ue/pillars.py)
    • proven by py -m u2ue --project <game> cycle --pillar 2
  3. pillar 3 human ergonomics: every concept a named class; diagrams generated from the code and gated (u2ue/pillars.py)
    • proven by py -m u2ue --project <game> cycle --pillar 3
  4. pillar 4 automation tools shipped: the Unity and Unreal automation a port needs ships in the package (u2ue/pillars.py)
    • proven by py -m u2ue --project <game> cycle --pillar 4
  5. pillar 5 proof and conformance: every judge has a plant that fails; conformance read from data (u2ue/pillars.py)
    • proven by py -m u2ue --project <game> cycle --pillar 5
  6. pillar 6 measured knowledge: every Unity rule measured by a probe case, stored per Unity version (u2ue/pillars.py)
    • proven by py -m u2ue --project <game> cycle --pillar 6
  7. pillar 7 generic, not one game: adapters and project files, no hard-wired paths in the core (u2ue/pillars.py)
    • proven by py -m u2ue --project <game> cycle --pillar 7
  8. pillar 8 packaging and release: a UPM package that installs into a fresh Unity and a fresh Unreal project (u2ue/pillars.py)
    • proven by py -m u2ue --project <game> cycle --pillar 8
  9. pillar 9 speed and proof of value: the porting speed and the percent-identical family, from records (u2ue/pillars.py)
    • proven by py -m u2ue --project <game> cycle --pillar 9
  10. pillar 10 safe operation: the toolkit never disturbs the person using the machine (u2ue/pillars.py)
    • proven by py -m u2ue --project <game> cycle --pillar 10
  11. pillar 11 run infrastructure: pinned, resumable runs from data, stoppable between steps (u2ue/pillars.py)
    • proven by py -m u2ue --project <game> cycle --pillar 11

Extensions (where the chain breaks, numbered by the step they branch from):

  • a A check reads FAIL - Red stops the cycle; the record keeps the check's output tail, so it says why without a re-run. (u2ue/pillars.py)*
  • b A check fails only as a recorded decision says it must - It reads HELD, naming the decision; failing any other way is FAIL. (u2ue/pillars.py)*

UC-08 The porter holds every key of a build to Unity on numbers

field
Level sea (user goal)
Primary actor porter - porting a game
Trigger a build is to be held to Unity on numbers before its photos are looked at
Scope every effect key of a project at once, Unity's particle state against what the built Niagara systems compute.
Precondition the keys are built in Unreal, and the owner allows a Unity window.
Minimal guarantee an emitter one side does not have is named UNPAIRED, never dropped.
Success guarantee every emitter OK, or its verdict named with its numbers.
Read from Chapter 9

Main success scenario (each step's postcondition is the next step's precondition):

  1. Write the cases (Chapter 9)
    • proven by py -m u2ue --project <game> conform cases --name <run>
  2. Read Unity (Chapter 9)
    • proven by py -m u2ue --project <game> window run <run window spec>
  3. Read Unreal (Chapter 9)
    • proven by py -m u2ue --project <game> trial run <run read spec>
  4. Compare (Chapter 9)
    • proven by py -m u2ue --project <game> conform diff --unity <record> --unreal <record> --report <file>
  5. Keep the score (Chapter 9)
    • proven by py -m u2ue --project <game> conform latest
    • uses conform.standing_run
  6. Name each miss (Chapter 9)
    • proven by py -m u2ue --project <game> conform classes --report <file>
  7. Follow the class, not the key (Chapter 9)

UC-09 A developer moves a tool onto the project file

field
Level sea (user goal)
Primary actor developer - extending the toolkit
Trigger a tool names a game's folder
Scope one tool that still names a game's folders.
Precondition the tool has a selftest, or one is written first.
Minimal guarantee run without the facade, the converted tool refuses by name.
Success guarantee the tool reads the project only through u2ue/env.py, and does what it did before.
Read from Chapter 18

Main success scenario (each step's postcondition is the next step's precondition):

  1. Replace each literal with need("U2UE_") for a project folder and part(name) for a toolkit folder. (Chapter 18)
  2. Prove the values (Chapter 18)
  3. Prove the refusal (Chapter 18)
  4. Prove the behaviour (Chapter 18)
  5. Run it through the facade (Chapter 18)
    • proven by py -m u2ue --project <game> tool <file>

UC-10 The toolkit measures a Unity behaviour in the owner's idle editor

field
Level sea (user goal)
Primary actor toolkit - its own runners
Trigger a rule the conversion needs is not measured
Scope one Unity behaviour, measured in the owner's own editor.
Precondition a probe and its judge are written, and a window spec names the probe, its inputs and its outputs.
Minimal guarantee the owner's editor is left as it was - every record and guard file md5-held, the probes removed, nothing replaced.
Success guarantee the fact file is written with the Unity version it was measured on.
Extends EPIC-1 at 7a
Read from Chapter 8

Main success scenario (each step's postcondition is the next step's precondition):

  1. Idle gate (Chapter 8)
    • proven by py -m u2ue --project <game> window check <spec.json>
    • proven by py -m u2ue --project <game> window run <spec.json>
  2. Presence watch (Chapter 8)
    • proven by py -m u2ue --project <game> window run <spec.json>
  3. The editor lock (Chapter 8)
    • proven by py -m u2ue --project <game> window run <spec.json>
  4. Compile headless first (Chapter 8)
    • proven by py -m u2ue --project <game> window run <spec.json>
  5. Nothing is replaced (Chapter 8)
    • proven by py -m u2ue --project <game> window run <spec.json>
  6. Wait for the real compile (Chapter 8)
    • proven by py -m u2ue --project <game> window run <spec.json>
  7. Trigger, wait, collect (Chapter 8)
    • proven by py -m u2ue --project <game> window run <spec.json>
  8. Play mode only when it must (Chapter 8)
  9. Take it out (Chapter 8)
    • proven by py -m u2ue --project <game> window run <spec.json>
  10. Read the console (Chapter 8)
    • proven by py -m u2ue --project <game> window run <spec.json>

Extensions (where the chain breaks, numbered by the step they branch from):

  • 2a The owner comes back - At any step the window leaves Play first, then takes the probes out (step 9); nothing else runs. (Chapter 8)
  • 7a Unity crashes in native code during a probe - ParticleSystem.Particle.GetMeshIndex on a renderer that is not a Mesh renderer with meshes kills the editor; a managed try/catch does not see it. Check the renderer before any renderer-dependent query, and write the field ABSENT otherwise. (Chapter 16)
  • 7b A probe's work never runs while the editor is in the background - EditorApplication.delayCall does not fire for an unfocused editor. Poll from EditorApplication.update. (Chapter 16)
  • 7c The first case a probe renders is wrong, and only that one - The first render after a probe sets up its scene can come out incomplete (measured: without the scene's ambient, so an ON - OFF difference read the ambient as light). Throw one or two renders away before the first case, and have the judge compare every OFF render of a surface against the others, so an incomplete one is refused by name instead of read as data. (Chapter 16)
  • 6a A measurement right after a recompile reproduces the old numbers - Entering Play while a compile is pending runs the old assembly. Wait until the editor assembly's timestamp is newer than the source and isCompiling reads false, then Play. (Chapter 16)

UC-11 Prove it before reporting it

field
Level sea (user goal)
Primary actor opus - the AI model
Trigger Port the Unity game at to Unreal with u2ue.
Scope one Unity game, from its project folder to an acceptance page the owner can check.
Precondition the toolkit is installed and verified (the manual's Chapter 3) and the Unity project is saved as text.
Stakeholders the porter wants the game in Unreal; the owner wants the cost known first and only their decisions asked.
Minimal guarantee every stage reads DONE from its own records, or says what it waits on, what it needs, or why it is absent.
Success guarantee port reads nothing left but the owner's decisions, and the cycle passes.
Included by EPIC-1, step 2, 3, 4, 5, 6, 7, 8, 9
Read from the u2ue skill

Main success scenario (each step's postcondition is the next step's precondition):

  1. Price the port: Price the port (the u2ue skill)
    • proven by py -m u2ue estimate --unity <unity project> --roots <the game's code folders>
  2. Describe the project: Describe the project (the u2ue skill)
    • proven by py -m u2ue --project <game> info
    • proven by py -m u2ue --project <game> inventory --survey
    • uses code.roots
  3. Run every stage a verb can: Run every stage a verb can (the u2ue skill)
    • proven by py -m u2ue --project <game> port
    • proven by py -m u2ue --project <game> port --run
  4. Take each stop to what it needs: Take each stop to what it needs (the u2ue skill)
    • proven by py -m u2ue --project <game> logic
  5. Hand the owner the page: Hand the owner the page (the u2ue skill)
    • proven by py -m u2ue --project <game> report
    • proven by py -m u2ue --project <game> metrics
  6. Prove it before reporting it: Prove it before reporting it (the u2ue skill)
    • proven by py -m u2ue --project <game> cycle

UC-12 The porter imports a Unity scene as an Unreal level and grades it

field
Level sea (user goal)
Primary actor porter - porting a game
Trigger one of the game's scenes is to run in Unreal
Scope one Unity scene, imported into Unreal as a new level.
Precondition the project file names the scene and its work folder, and the scene's own fidelity baseline exists.
Minimal guarantee a scene with no baseline is refused, never graded against another scene's numbers, and a sheared node's error is a number the owner decides on.
Success guarantee the imported level passes the scene's fidelity gate, every leg at or better than its baseline.
Included by EPIC-1, step 6
Read from Chapter 6

Main success scenario (each step's postcondition is the next step's precondition):

  1. shear: The verb reads a scene either as the glTF file the scene pipeline exports (below) or straight from the Unity scene file, with no export. (Chapter 6)
    • proven by py -m u2ue --project <game> shear --gltf <path> --json <path>
    • proven by py -m u2ue --project <game> shear --from <path>
  2. scene --dry: the scene's paths, opened; the host's state (Chapter 6)
    • proven by py -m u2ue --project <game> scene --dry
    • uses scene.dir
  3. scene export: REFUSED here: runs in the owner's editor, in a window - prints the trigger (Chapter 6)
    • proven by py -m u2ue --project <game> scene export
    • uses scene.dir
  4. scene import: the glTF into a NEW level through Interchange (Unreal, headless) (Chapter 6)
    • proven by py -m u2ue --project <game> scene import
    • uses scene.dir
  5. scene readback: the saved level read back (Unreal, headless) (Chapter 6)
    • proven by py -m u2ue --project <game> scene readback
    • uses scene.dir
  6. scene check: the fidelity gate against the scene's own baseline (no editor) (Chapter 6)
    • proven by py -m u2ue --project <game> scene check
    • uses scene.dir

UC-13 Opus ports one effect gap by the route protocol

field
Level sea (user goal)
Primary actor opus - the AI model
Trigger the acceptance page lists an absent emitter root, ordered by what porting it brings back
Scope every particle effect the game fires, from its Unity prefab to a Niagara system.
Precondition a project file names the Unity project and the Unreal host, and u2ue info exits 0.
Stakeholders the porter wants the effects to look the same; the owner wants every difference named and only their decisions asked.
Minimal guarantee an effect or emitter that is not ported is named on the acceptance page with its reason - never dropped.
Success guarantee every effect the game fires draws in the Unreal build as Unity draws it, and every gap is named.
Included by EPIC-1, step 7
Read from the u2ue-port skill

Main success scenario (each step's postcondition is the next step's precondition):

  1. Census with today's converter, offline, over the whole IR: which emitters the route would gain, and what refuses them NEXT. (the u2ue-port skill)
  2. Find the measurement you already have (the conformance part's -facts.json, cases naming the module; py -m u2ue find lists them). (the u2ue-port skill)
    • proven by py -m u2ue find <module>
    • proven by py -m u2ue --project <game> window check <spec.json>
    • proven by py -m u2ue --project <game> window run <spec.json>
  3. Write the route behind a VFXPORT_ switch, default OFF (the u2ue-port skill)
  4. Trial (the u2ue-port skill)
    • proven by py -m u2ue --project <game> judge --prove
    • proven by py -m u2ue --project <game> trial plan <spec.json>
    • proven by py -m u2ue --project <game> trial run <spec.json>
    • proven by py -m u2ue --project <game> trial stop
  5. Flip the default with its evidence row (patch_flip_defaults.py), then flip_audit.py clean (every switch a trial set reads default ON, or is named deliberately OFF with what it waits on). (the u2ue-port skill)
  6. Write it down (the u2ue-port skill)

Extensions (where the chain breaks, numbered by the step they branch from):

  • 2a The rule is not measured - Measure it in Unity before the route is written - a probe and its judge in one window the owner allows - never from the docs. (the u2ue-port skill)
  • 4a A photo differs from Unity's - A photo is one random draw in Unreal against Unity's fixed seed: the difference counts only past two draws' spread. (the u2ue-port skill)

UC-14 Record the slice and take the next

field
Level sea (user goal)
Primary actor opus - the AI model
Trigger Move the logic of into Model, View, Controller with the u2ue-mvc skill.
Scope a Unity game's logic, the MonoBehaviours that hold its state, rules and drawing, and the engine-free model they move into.
Precondition the game has an engine-free model (u2ue-logic, steps 1 to 6) and a project file that names its hosts.
Stakeholders the porter wants one home per piece of state and every engine running the same code; the owner wants the game to play as it did; a reviewer wants to read the shape (input, controller, model, events, view) instead of the code.
Minimal guarantee no slice lands while u2ue slice is red, and nothing claims the game plays the same until it was played.
Success guarantee every rule runs in a Model that names no engine type, each engine supplies only Views, and the game plays as before (or a difference was fixed on purpose and written down).
Read from the u2ue-mvc skill

Main success scenario (each step's postcondition is the next step's precondition):

  1. Record the baseline before anything moves: run the gate once on the untouched code and record which tests fail before the refactor starts, and why. (the u2ue-mvc skill)
    • proven by py -m u2ue --project <game> slice --baseline --because <why these may fail>
  2. Sort the slice's MonoBehaviours: give every type in the slice its part by the sorting rule above, and write it beside the type in the slice's notes. (the u2ue-mvc skill)
    • proven by py -m u2ue --project <game> inventory
  3. Draw the target before moving anything: draw the slice's Models, Rules, Views and its Controller, with the Record each Model is made from. (the u2ue-mvc skill)
    • proven by py -m u2ue --project <game> uml mermaid --focus <TypeA> <TypeB>
  4. Give each piece of state one home: cut the slice's Unity files into a scratch overlay (slice cut, which records each live file's hash) and make every edit there, never in the live project. (the u2ue-mvc skill)
    • proven by py -m u2ue --project <game> slice cut --overlay <DIR> <Assets/...>
    • proven by py -m u2ue --project <game> slice --overlay <DIR>
  5. Let the rules take the Model: change each rule of the slice to take the Model class itself, grouped by topic into Rules; delete the one-rule interfaces it no longer needs. (the u2ue-mvc skill)
    • proven by py -m u2ue --project <game> slice
  6. Commands in, events out: the slice's player and AI actions become commands given to the Model's Apply; every state change it makes returns an event, in order, instead of calling a View. (the u2ue-mvc skill)
    • proven by dotnet test u2ue/runtime/U2ue.Runtime.Tests
  7. Views play events; the HUD reads its view model: each View plays the events that name its Model through the Controller's U2ue.Runtime.PlaybackQueue; the HUD reads a view model the Controller advances as events finish. (the u2ue-mvc skill)
    • proven by py -m u2ue --project <game> slice land --overlay <DIR> --seed <N>
    • uses PlaybackQueue
  8. Record the slice and take the next: write down what moved, what the slice's gates read, and the next slice. (the u2ue-mvc skill)
    • proven by py -m u2ue --project <game> logic

UC-15 The porter moves a game's code into an engine-free model

field
Level sea (user goal)
Primary actor porter - porting a game
Trigger the game's rules live in MonoBehaviours, which Unreal cannot run
Scope the game's code - its rules, its per-frame order, its data.
Precondition a project file names the game and its code folders.
Stakeholders the porter wants the game running on Unreal, the same; the owner wants only their decisions asked; a reviewer wants the design reviewable from its class model, not line by line.
Minimal guarantee what the toolkit cannot do for a rule is said, and the model's gates stop an engine reference.
Success guarantee one engine-free model both engines run, with the same answers by the bit.
Included by EPIC-1, step 3, 4, 5, 6
Read from Chapter 5

Main success scenario (each step's postcondition is the next step's precondition):

  1. Inventory the code (Chapter 5)
    • proven by py -m u2ue --project <game> inventory --survey
    • proven by py -m u2ue --project <game> inventory
    • proven by py -m u2ue --project <game> uml extract
    • proven by py -m u2ue --project <game> uml mermaid --focus TypeA TypeB
    • uses code.roots
  2. Read the frame order (Chapter 5)
  3. Give the model Unity's runtime rules (Chapter 5)
    • uses Coroutines, Digest, FloatBits, Handle, IPresenter, PlaybackQueue, Point, SeededRandom, TrailLaw, UnityClock and 3 more
  4. Put the engine behind seams (Chapter 5)
    • uses IFileStore, IJsonCodec, IKeyValueStore, ILog, IRandomSource, ITextAssets
  5. Read the data, never retype it (Chapter 5)
    • proven by py -m u2ue --project <game> data --from <scene|prefab|asset> --script <ClassName>
  6. Cut the model, then gate it (Chapter 5)
    • proven by py -m u2ue --project <game> scaffold --name <Model> --dir <a folder outside Assets>
    • proven by py -m u2ue --project <game> check --only model
    • uses model.hosting, model.layers, model.root, model.scan, model.unreal_links
  7. Prove the rules agree across runtimes (Chapter 5)
    • proven by py -m u2ue --project <game> digest run --entry <Ns.Cases.Build> --cases <Cases.cs>
    • proven by py -m u2ue --project <game> digest faithful
    • proven by py -m u2ue --project <game> parity
    • uses mono.faithful.refs, parity.dir, Digest
  8. Write the hosts (Chapter 5)
    • uses UnityFrame

Extensions (where the chain breaks, numbered by the step they branch from):

  • 1a A rule does value-type maths (Vector3, Mathf, Color) - The inventory counts Unity's value types as a family of their own, so such a rule is not pure: its arithmetic is UnityEngine's. It does not move as written: where those types live in an engine-free model is the owner's decision, made once for the whole model ("Floats across runtimes" below has the two answers), and the rule waits for it. (Chapter 5)
  • 7a Text built from floats differs between Unity and .NET - Unity's Mono rounds float text to seven significant digits first, rounds halves away from zero, and prints a value that rounds to zero without a sign. Any number a player reads, or a stream compared against Unity, goes through one formatter that reproduces Mono's rules. (Chapter 16)
  • 7b Float results differ by one ULP - Mono may keep a float expression at higher precision. u2ue parity names every such row; an allowance pins the exact row and bits, and the fix (explicit float locals) moves Unity's own value, so it is the owner's call. Chapter 14 has what the standards allow and the two differences that are not rounding. (Chapter 16)
  • 7c System.Text.Json writes {} for a Unity data class - Unity's JsonUtility serializes public fields; System.Text.Json ignores fields unless IncludeFields = true. (Chapter 16)

UC-16 Record the slice and take the next one

field
Level sea (user goal)
Primary actor opus - the AI model
Trigger Port the logic of the Unity game at with u2ue, project name .
Scope a Unity game's C# - its MonoBehaviours, coroutines and frame order - and the engine-free model it moves into.
Precondition the game's Unity project is on disk serialized as text, and a project file names it (step 0).
Stakeholders the porter wants the game running on Unreal, the same; the owner wants only their decisions asked; a reviewer wants the design reviewable from its class model, not line by line.
Minimal guarantee nothing is invented - a rule that cannot move is named with its reason, and a red gate stops the step.
Success guarantee the game's rules run in one model, Unity's runtime and the Unreal host give the same bits (u2ue parity exits 0), and the game still plays.
Included by EPIC-1, step 3, 4, 5, 8
Read from the u2ue-logic skill

Main success scenario (each step's postcondition is the next step's precondition):

  1. Read the game before touching it: survey the Assets folders, name the game's OWN code folders as code.roots (vendor packages live in Assets too - never guess which are the game's), then inventory them. (the u2ue-logic skill)
    • proven by py -m u2ue --project <game> inventory --survey
    • proven by py -m u2ue --project <game> inventory
    • uses code.roots
  2. Draw the class model of ONE slice before moving anything (UML steers): pick the first slice - one feature whose rules use the fewest Unity families (a damage formula, a scoring rule, an inventory stack). (the u2ue-logic skill)
    • proven by py -m u2ue --project <game> uml extract
    • proven by py -m u2ue --project <game> uml mermaid --focus <TypeA> <TypeB>
  3. Sort the slice's types and members: give every type in the slice ONE destination - CORE (a pure rule: moves as is), AGGREGATE (the state and rules inside a (the u2ue-logic skill)
    • proven by py -m u2ue --project <game> inventory
  4. Cut the Core: create the engine-free model OUTSIDE the Unity Assets tree, declared in the project file. (the u2ue-logic skill)
    • proven by py -m u2ue --project <game> scaffold --name <Model> --dir <folder>
  5. Put the platform seam in first: every log line, file read, preference, JSON document and random draw the slice makes goes through U2ue.Runtime.Platform (ILog, ITextAssets, IKeyValueStore, IFileStore, IJsonCodec, IRandomSource / SeededRandom) - never re-declared on a rule's host (the reference port found a log line declared on five hosts and a random draw on seven before it did this). (the u2ue-logic skill)
    • proven by py -m u2ue --project <game> check --only model
    • proven by dotnet test u2ue/runtime/U2ue.Runtime.Tests
    • uses IFileStore, IJsonCodec, IKeyValueStore, ILog, IRandomSource, ITextAssets, SeededRandom
  6. Move the slice's rules into the Core: move the code (do not rewrite it) into the aggregate; the MonoBehaviour now holds one aggregate and forwards its properties to it, so state has one home. (the u2ue-logic skill)
    • proven by py -m u2ue --project <game> check --only model
    • proven by dotnet test <Model>.Core.Tests
  7. Emit events; replay them: each rule that changes what the player sees appends an event to an ordered, append-only list instead of calling the view. (the u2ue-logic skill)
    • proven by dotnet test u2ue/runtime/U2ue.Runtime.Tests
    • proven by dotnet test <Model>.Core.Tests
    • uses PlaybackQueue
  8. Keep Unity's frame order: per-frame code the slice keeps (Update, LateUpdate, coroutines) registers with ONE UnityFrame in its script execution order (inventory's frame-order table, read from the .cs.meta files); coroutines run on U2ue.Runtime.Coroutines. (the u2ue-logic skill)
    • proven by py -m u2ue --project <game> inventory
    • proven by dotnet test u2ue/runtime/U2ue.Runtime.Tests
    • uses Coroutines, UnityFrame
  9. Prove it: the same answers, by the bit: write the slice's cases ONCE, as a static method returning a Digest (no NUnit in that file), driving the moved rules the way the game drives them (its own constants, READ with file:line). (the u2ue-logic skill)
    • proven by py -m u2ue --project <game> digest run --entry <Ns.Cases.Build> --cases <Cases.cs>
    • proven by py -m u2ue --project <game> parity
    • uses parity.dir, Digest
  10. The Unreal host: the game gets its OWN .uproject, made by u2ue host the way a customer makes one: name it in the project file's unreal.host block (the template, each plugin with its source and pinned commit, the AutoSDK root, the digest's entry and cases), then run the steps in order from native PowerShell - each refuses while an Unreal runs and is judged by its proof line, never an exit code. (the u2ue-logic skill)
    • proven by py -m u2ue --project <game> host plan
    • proven by py -m u2ue --project <game> host create
    • proven by py -m u2ue --project <game> host status
    • proven by dotnet build u2ue/templates/unreal/U2ue.Unreal
    • proven by py -m u2ue.seam --project <game> --list
    • proven by py -m u2ue --project <game> parity --require Unreal
    • uses PlaybackQueue, UnityFrame
  11. Record the slice and take the next one: write the slice's record to /slices/slice-.json (logic reads it there) - the slice, its first commit and its parity commit (the tempo), the gates' output - and take the next slice, bigger. (the u2ue-logic skill)
    • proven by py -m u2ue --project <game> check --only model
    • uses work.effects

Extensions (where the chain breaks, numbered by the step they branch from):

  • 11a step 1 - the reader is lexical - a call through reflection or a helper is not seen; a miss is UNKNOWN, never "does not use" - the reader is lexical - a call through reflection or a helper is not seen; a miss is UNKNOWN, never "does not use". (the u2ue-logic skill)
  • 11b step 1 - "pure" means no Unity API AND no Unity value type (Vector, Mathf, Color are a family of their own in the inventory): a rule that does Vector3 maths cannot move into an engine-free model as written - "pure" means no Unity API AND no Unity value type (Vector, Mathf, Color are a family of their own in the inventory): a rule that does Vector3 maths cannot move into an engine-free model as written. (the u2ue-logic skill)
  • 11c step 3 has no tool yet - a host-kind census for any game's model - label by hand by the rule above: a non-void member is an ANSWER. (the u2ue-logic skill)
  • 11d step 9 - the cases' INPUTS must be exact on every runtime - make them by integer arithmetic and write each one to the sheet (_in rows) - Measured on the second game's first slice: a driver that made its own target angles with float maths produced 177 false differences in 321 rows; with exact inputs the rule's true difference was 2 rows. (the u2ue-logic skill)
  • 11e step 9 - UnityMono is Unity's runtime, not the Editor - u2ue digest faithful measures one against the other on an Editor-recorded digest (Unity 6000.3: 383 of 383 rows identical); a Unity version without that measurement is labelled UNMEASURED in the provenance, and its Mono answer is not called the Editor's. (the u2ue-logic skill)

UC-17 The porter lays out the game's uGUI screens in Unreal

field
Level sea (user goal)
Primary actor porter - porting a game
Trigger a screen of the game is to run in Unreal
Scope one game's uGUI screens, laid out in Unreal by a port of uGUI's own solver.
Precondition each screen can be reached in Play mode in the game's own editor.
Minimal guarantee a font whose glyph indices differ is refused, and a panel with no view model and binding is not drawn.
Success guarantee each captured screen is laid out in Unreal as Unity resolved it.
Included by EPIC-1, step 5
Read from Chapter 6

Main success scenario (each step's postcondition is the next step's precondition):

  1. Capture the Canvas in the game's own Unity Editor in Play mode: every RectTransform, its anchors and its components, as Unity resolved them. (Chapter 6)
  2. Hold the library to Unity (Chapter 6)
    • proven by py -m u2ue --project <game> ui test
  3. Convert each capture into a folder Unreal reads: py -m u2ue --project ui convert --screen NAME [--out DIR] (--out defaults under the project's work.ui). (Chapter 6)
    • proven by py -m u2ue --project <game> ui convert <capture dir> --screen <path> [--out <path>
  4. Bind each panel to its view model in the game's own host; only a panel with a view model and a binding is drawn. (Chapter 6)
  5. Paint the bound panels in one UUserWidget.OnPaint, laid out by the solver from the converted folder. (Chapter 6)

UC-18 The porter takes a new game from its project file to its first report

field
Level sea (user goal)
Primary actor porter - porting a game
Trigger a game the toolkit was not built on is to be ported
Scope one game, from its project file to its first report.
Precondition the toolkit is installed and verified (Chapter 3).
Minimal guarantee every path the project names is opened, and every key the game must account for is listed before anything is built.
Success guarantee the acceptance page and the numbers, each number read from a record or naming the record it waits for.
Included by EPIC-1, step 2, 3, 7, 8
Read from Chapter 4

Main success scenario (each step's postcondition is the next step's precondition):

  1. Describe the game and open every path (Chapter 4)
    • proven by py -m u2ue --project <game> info
    • uses adapter, unity.root, unreal.content_root, unreal.uproject, work.effects, work.photos
  2. Find the game's own code (Chapter 4)
    • proven by py -m u2ue --project <game> inventory --survey
    • uses code.roots
  3. Inventory the code (Chapter 4)
    • proven by py -m u2ue --project <game> inventory
  4. Read the data the inspector holds (Chapter 4)
    • proven by py -m u2ue --project <game> data --from <path> --script <DataClass> --tsv <path>
  5. Extract the effects (Chapter 4)
    • proven by py -m u2ue --project <game> extract
    • uses adapter, work.guid_index, work.ir, work.resolve
  6. Check before building (Chapter 4)
    • proven by py -m u2ue --project <game> check
  7. Build, read, photograph (the Unreal host) (Chapter 4)
    • proven by py -m u2ue --project <game> build --dry
    • proven by py -m u2ue --project <game> build
    • proven by py -m u2ue --project <game> read --tag <TAG>
    • proven by py -m u2ue --project <game> photo --tag <TAG>
  8. Report and measure (Chapter 4)
    • proven by py -m u2ue --project <game> report --out <path>
    • proven by py -m u2ue --project <game> metrics

Extensions (where the chain breaks, numbered by the step they branch from):

  • 7a A headless Unreal never finishes and its log grows to hundreds of megabytes - UnrealSharp finds dotnet by the PATH entry Program Files\dotnet\ with the trailing backslash. Git Bash hands PowerShell a PATH without it, so UnrealSharp reports ".NET SDK can't be found" and, under -unattended, raises the dialog again forever (measured: a 634 MB log, nothing built). Run every Unreal verb from native PowerShell. The verbs refuse up front when they are launched from Git Bash. (Chapter 16)
  • 5a An effect's blend mode is wrong - The blend mode is a number in the material (_DstBlend == 1 is additive), never the shader's name. (Chapter 16)
  • 7b A texture looks different in Unreal although the file is the same - Unity samples its imported texture (mip chain, alpha fill, size caps), not the source file. The import is in Library/Artifacts and can be read offline (effects_tools/unity_tex_artifact.py); validate the match against the source, since the artifact index can point at a neighbouring asset. (Chapter 16)
  • 6a A gate reports a symbol ABSENT that you know exists - Check whether the port moved it (into the model, for example) before believing the gate. Widen the gate to follow the move, then re-run its plants. (Chapter 16)
  • 7c The photo of an effect differs from Unity's in a way the data does not - A photo is one draw of a random process, and a frame can catch a capture artefact. u2ue metrics counts the flagged frames labelled RANDDRAW (one draw) or GRIDTICK apart, as the capture's difference, not the port's. Compare several frames and the read-back data before calling a route wrong. (Chapter 16)
  • 8a u2ue metrics prints STALE - An input is older than the newest build. Re-run the step that writes it (the read-back sweep, the photo pass); the number is never presented as current until then. ABSENT means the record a number needs is not on disk, and names it. (Chapter 16)
  • 7d A long build stops at exactly the shell tool's timeout, leaving the content half old and half new - Stopping a background task kills its children, including UnrealEditor-Cmd. Before a long launch, compare the tool's timeout with the script's own watchdog and give the tool the larger one. (Chapter 16)
  • 7e Two Unreal runs at once - One headless Unreal at a time. Every verb that starts Unreal (build, read, photo, scene, host) asks the adapter's host_busy and refuses while an Unreal, or a build queue the game's adapter names, holds the host. --dry on build, read, photo or scene shows the host's state. (Chapter 16)
  • 7f Niagara draws nothing in an editor script - -run=pythonscript asserts, and -ExecutePythonScript quits before the tick loop runs. The editor world never ticks actors, so Niagara simulates only inside Simulate or Play-In-Editor unless something advances it. The read-back advances each system itself: NiagaraSimCacheFunctionLibrary's immediate capture with bAdvanceSimulation (effects_tools/u1e_color_size_readback.py, which u2ue read runs). (Chapter 16)
  • 7g A headless run plays sound through the user's speakers, or records silence - Pass -DeterministicAudio (the non-realtime renderer: nothing reaches a device, and each tick renders its own delta) and -ini:Engine:[Audio]:UnfocusedVolumeMultiplier=1.0 (an unfocused application otherwise mixes at volume 0). (Chapter 16)
  • 7h An UnrealSharp editor wedges while files are being generated - With automatic hot reload on, the editor recompiles a managed file the instant it is written, mid-write, fails, and can stop responding. Set AutomaticHotReloading=Off in the host's DefaultEditorPerProjectUserSettings.ini, or keep the editor closed while a tool writes managed C#. (Chapter 16)
  • 4a The reader refuses a scene with m_AddedGameObjects or m_AddedComponents - A prefab instance that adds an object or a component to its source prefab is not ported yet, and the nested-prefab expander refuses it by name. Removals are applied: m_RemovedComponents and m_RemovedGameObjects take the component, or the object with its child subtree, out of the instance. u2ue data --no-expand reads the scene's own components without expanding instances. (Chapter 16)
  • 5b A nested prefab's object cannot be found by its fileID - A nested object's id is the instance's id XOR the source object's id, with the top bit cleared. (Chapter 16)
  • 5c A material's values look like its shader's defaults - A material variant stores only what it overrides; the rest comes through m_Parent. Read the chain. (Chapter 16)

UC-19 The owner assembles the toolkit's repository from its own trees

field
Level sea (user goal)
Primary actor owner - whose product it is
Trigger the owner wants the toolkit's current state in its repository
Scope the toolkit's own trees, assembled into one repository by the manifest in u2ue/release.py.
Precondition the target folder is empty, or a checkout an earlier release wrote.
Minimal guarantee a secret in a shipped file refuses the whole release, and every file left out is named with its reason.
Success guarantee the repository holds exactly what the manifest ships, and release --check says it is current.
Read from Chapter 18

Main success scenario (each step's postcondition is the next step's precondition):

  1. See what would ship (Chapter 18)
    • proven by py -m u2ue release --to <DIR> --dry
  2. Assemble it (Chapter 18)
    • proven by py -m u2ue release --to <DIR>
  3. Prove it is current (Chapter 18)
    • proven by py -m u2ue release --check --to <DIR>
  4. Prove it runs from a fresh clone (Chapter 18)
    • proven by dotnet test u2ue/runtime/U2ue.Runtime.Tests
    • proven by py -m u2ue.verbs.release --selftest
  5. Leave the history to the owner (Chapter 18)

UC-20 Opus runs the effect pipeline from the prefabs to the metrics

field
Level sea (user goal)
Primary actor opus - the AI model
Trigger a project file names the game and its Unreal host
Scope every particle effect the game fires, from its Unity prefab to a Niagara system.
Precondition a project file names the Unity project and the Unreal host, and u2ue info exits 0.
Stakeholders the porter wants the effects to look the same; the owner wants every difference named and only their decisions asked.
Minimal guarantee an effect or emitter that is not ported is named on the acceptance page with its reason - never dropped.
Success guarantee every effect the game fires draws in the Unreal build as Unity draws it, and every gap is named.
Included by EPIC-1, step 7
Read from the u2ue-port skill

Main success scenario (each step's postcondition is the next step's precondition):

  1. info: every path the project names, opened - exit 1 = fix the project file first (the u2ue-port skill)
    • proven by py -m u2ue --project <game> info
  2. extract: Unity prefabs -> the engine-neutral IR (no editor); every key an IR or a named refusal (the u2ue-port skill)
    • proven by py -m u2ue --project <game> extract
  3. check: the toolkit's selftests + the field gates: red = an unread Unity field, do not build (the u2ue-port skill)
    • proven by py -m u2ue --project <game> check
  4. build: then build: the IR -> Niagara systems (Unreal), one record per key (the u2ue-port skill)
    • proven by py -m u2ue --project <game> build --dry
  5. read: the built systems read back frame by frame -> the read-back checks, each with a plant (the u2ue-port skill)
    • proven by py -m u2ue --project <game> read
  6. photo: Unreal frames paired with Unity's -> sheets you LOOK at (the u2ue-port skill)
    • proven by py -m u2ue --project <game> photo
  7. report: the acceptance page: every key, every gap by reason and by ROOT, every stand-in (the u2ue-port skill)
    • proven by py -m u2ue --project <game> report
  8. metrics: the numbers, each from a record with its definition (the page's own) (the u2ue-port skill)
    • proven by py -m u2ue --project <game> metrics
  9. tempo: each verified route's first code -> flip, from git (the u2ue-port skill)
    • proven by py -m u2ue --project <game> tempo

Extensions (where the chain breaks, numbered by the step they branch from):

  • 1a info exits 1 - A path the project names is missing: fix the project file before any other verb. (the u2ue-port skill)

UC-21 The porter verifies the toolkit on their machine

field
Level sea (user goal)
Primary actor porter - porting a game
Trigger the toolkit is installed or updated
Scope the toolkit itself, on this machine.
Precondition the requirements above are installed and a project file exists.
Minimal guarantee a tool whose selftest fails is named.
Success guarantee every selftest passes, the runtime library's tests pass, and the manual matches the code.
Read from Chapter 3

Main success scenario (each step's postcondition is the next step's precondition):

  1. check --only selftests: every tool's own selftest (Chapter 3)
    • proven by py -m u2ue --project <game> check --only selftests
  2. dotnet test u2ue/runtime/U2ue.Runtime.Tests: the runtime library (Chapter 3)
    • proven by dotnet test u2ue/runtime/U2ue.Runtime.Tests
  3. py u2ue/manual/build.py --check: this manual is current (Chapter 3)
    • proven by py u2ue/manual/build.py --check

18. Extending the toolkit

Who this is for: the toolkit developer adding to u2ue, and the reviewer checking it - one recipe per kind of addition, and which tool does what. After it you can add any of them and name the check that proves it.

The toolkit grows in six ways: a game adapter, a verb, a converter route, a material family, a measured rule and a selftest. Two more sections move a concept into a class and an older tool onto the project file. Each recipe names one place to edit and one check that proves the addition works. A recipe with numbered steps opens with its dressed fields (scope, precondition, the two guarantees and the trigger, as Reading UML and use cases defines them), because Chapter 17 reads each such recipe as a use case. The second half of the chapter lists the tools a port runs, by work package (one group of tools per part of a port), for anyone changing or reviewing them.

A game adapter

Scope: one game-specific answer the default adapter gets wrong. Precondition: a project file that info opens. Minimal guarantee: a question the adapter does not override keeps Unity's own answer. Success guarantee: info names the adapter it loaded, and extract holds the key list to the adapter's spawn rules. Trigger: a default answer is wrong for the game.

Most games need none. The default adapter, unity_project, answers the three game-specific questions with Unity's own rules:

question the default answer
effect_keys(p, env, resolve) - which prefabs are the game's effects every prefab under effects.key_source.roots holding a ParticleSystem
spawn_rules - what starts when the game spawns an effect "unity": the systems marked Play On Awake (Unity starts them when the effect is spawned) and their sub-emitters
host_busy(p) - why the Unreal host is not free any Unreal editor process running (one headless Unreal at a time)

In each signature p is the loaded project; resolve is the file the key list is written to, which the IR reader then reads.

# u2ue/adapters/mygame.py - discovered by name; no edit to the core
from . import UnityProject

class MyGame(UnityProject):
    name = "mygame"
    def effect_keys(self, p, env, resolve):
        ...   # write {"keys": [...]} to `resolve`; return 0, or non-zero with the reason printed

ADAPTER = MyGame
  1. Find the question. Read the default answers above against the game; an adapter overrides only a question whose default answer is wrong for it.
  2. Write the adapter. u2ue/adapters/<game>.py: a subclass of UnityProject that overrides that question alone, and ADAPTER = <the class>. It is discovered by name; nothing in the core is edited.
  3. Name it. Set "adapter": "<game>" in the project file.
  4. See it load. py -m u2ue --project <name> info names the adapter it loaded.
  5. See it hold. py -m u2ue --project <name> extract refuses a key list that contradicts the adapter's spawn_rules (keys read with Unity's rule carry a unity. prefix).

The reference port's adapter overrides all three: its keys are the effects its battles actually fire, resolved the way the game's own code resolves them; its spawn rule is the game's own ("game"); and its host also reads busy while its own build queues run.

A verb

Scope: one command of the facade. Precondition: the work it runs exists as a module or a tool on disk. Minimal guarantee: a verb that wraps a tool which is not on disk stops, by name; it never skips. Success guarantee: the command line, find and Chapter 20 all show the verb, from its one registry row. Trigger: a step of a port has no command.

  1. Write the module. u2ue/verbs/<name>.py: a docstring, which becomes the verb's page in Chapter 20, and run(p, argv), where p is the project, or None for a verb that needs none.
  2. Register it. One row in VERBS in u2ue/verbs/__init__.py, in the order a port runs the verbs. The command line, the verb list, find and this manual all read that registry; a verb added anywhere else is invisible.
  3. Find it. py -m u2ue find <name> lists it under verb, with the file it lives in.
  4. Rebuild the manual. py u2ue/manual/build.py writes its page into Chapter 20; py u2ue/manual/build.py --check exits 1 until it has.

A verb that wraps a tool runs it as a subprocess through u2ue.tools, with the project's U2UE_* environment, below normal priority.

A converter route

Scope: one Unity behaviour the converter did not port before (Chapter 7). Precondition: the behaviour is measured or read. Minimal guarantee: until the route is flipped, it changes no call the converter makes. Success guarantee: the route is on by default, with its evidence in the flip table. Trigger: the acceptance page names a gap no route ports.

  1. Measure or read the behaviour (Chapter 8).
  2. Write the route behind VFXPORT_<NAME>, read default OFF.
  3. Prove it offline with whole_trace.py: off, identical calls everywhere; on, exactly the predicted emitters change.
  4. Trial it: build, read, judge, photograph and LOOK.
  5. Flip it: one row in vfxport/patch_flip_defaults.py's table with its evidence. u2ue tempo and u2ue metrics read that table.

A material family

Scope: one Unity shader and every material that uses it. Precondition: the shader's .shadergraph can be read. Minimal guarantee: every surface the shader exposes is accounted for; none is dropped silently. Success guarantee: every material of the family is an instance of one authored parent, its values read from its .mat. Trigger: an effect material's shader has no Unreal parent.

Unity effect materials use custom shaders, so each distinct shader needs one Unreal parent material, authored once:

  1. Author the parent by a script, never by hand (the reference port's vm1_author.py, for its largest family, a vendor's uber shader graph: one Shader Graph whose many features are switched by its keywords and properties).
  2. Account for every surface. vm1_read_shadergraph.py reads every property, keyword and node the shader graph exposes off the .shadergraph file, never typed; vm1_account.py marks each APPLIED (the Unreal material carries it), INERT with the arithmetic that shows it changes nothing, or ABSENT with the reason. The count of unaccounted surfaces must be 0.
  3. Instance it. Every material of the family becomes an instance of the parent, with its values read from its .mat.

A measured rule

Scope: one rule the converter uses, measured in Unity. Precondition: the rule cannot be read from Unity's data or its source. Minimal guarantee: a bake the judge cannot read the rule from is refused, with its numbers. Success guarantee: the converter re-derives the rule from the fact file at every build. Trigger: the converter needs a rule Unity's files do not state.

  1. Write the judge first, with planted wrong answers it must refuse (Chapter 8).
  2. Write the probe: an Editor script that bakes the behaviour, placing a real prefab only through ProbeSpawn.
  3. Run it in a window: py -m u2ue --project <name> window run <spec.json> waits until the editor's owner is away (no cursor move and no key for 600 s).
  4. Keep the fact file the judge reads off the bake, with the Unity version it was measured on.
  5. Re-derive it at build time. The converter reads the rule from the fact file when it builds, so the build stops if the rule stops holding.

A selftest

Scope: one tool that can be wrong. Precondition: the tool runs offline, or the reason it cannot is measured. Minimal guarantee: a tool whose selftest cannot run offline is listed with that reason, never skipped silently. Success guarantee: u2ue check runs the selftest and Chapter 21 lists it. Trigger: a tool that can be wrong is written.

  1. Plant the defects. The tool carries --selftest with planted defects, and must refuse each one.
  2. Register it in u2ue/survey/pt1_selftests.py (RUNS: the tool, its folder, its exact command). A tool whose selftest cannot run offline goes in NOT_RUN with the measured reason. A gate written against one game's own model, adapter or HUD goes in that game's project file instead, under selftests (runs and not_run), so the package never lists a tool it does not ship.
  3. Run it with the rest. py -m u2ue --project <name> check --only selftests runs it.
  4. See it listed. py u2ue/manual/build.py writes it into Chapter 21's selftest list.

A concept

A concept is a row of u2ue/CONCEPTS.md, drawn in Chapter 22's concept model. One that is only functions or data (PARTIAL) moves to a class (EXISTS) in four moves: its class is drawn in u2ue/CONCEPTS.md first, with the members it needs and the concepts it talks to; the class is written, and the existing functions move under it as methods, one at a time; each move is proven output-identical (the tool's own selftest, whole_trace.py for the converter, the records it writes); and only then its row says EXISTS with the class path. u2ue/survey/concepts_gate.py checks that row against the code, and the count it prints rises.

Every rule traced to its probe

A fact file records the format its probe writes, and the probe's source holds that literal. u2ue/survey/rule_probes.py reads both as text and attributes each fact file: ATTRIBUTED when exactly one writer holds its format (a Unity probe first, then the toolkit's own Python, then the scripts of the lane part), AMBIGUOUS when several do, ORPHAN when none does (its probe is gone), UNFORMATTED when the file names no format. A run over the toolkit's facts (2026-10-17):

py u2ue/survey/rule_probes.py
RULES ATTRIBUTED 189 of 220 (orphan 0, ambiguous 3, unformatted 28)

An orphan is a measured rule nobody can re-measure.

Where the toolkit's parts live

The facade is the u2ue/ package (Chapter 22 maps its modules). u2ue/tools.py names each part's folder once (PARTS). Setting U2UE_TOOLKIT_ROOT=<root> resolves every part to <root>/<part>, which is the layout of the release package. A tool never names another part's absolute path; it asks tools.part(name).

The first three of Chapter 1's five layers (the product), by module:

  • Unity readers, offline. u1e_ir and t1_guid_index (the YAML prefab reader: nested, variant and legacy prefabs, m_RemovedComponents); unity_tex_artifact (Unity's own imported textures off Library/Artifacts, every mip); u1e_builtin_names (the built-in resources in unity_builtin_extra); u1e_alpha and u1e_alphadilate (alpha derivations); u1e_psdtex (a PSD inside a PNG).
  • Shuriken to Niagara. build_niagara and shuriken_size; the flip table patch_flip_defaults.TABLE and the OFF list in flip_audit; the measured facts in shared/conformance/*.json.
  • The proof machinery. u1e_color_size_readback and its sweep checks, the judges and their plants, the photo pairs and sheets, the acceptance report, and u2ue metrics.

A tool that still names one game's folder instead of reading the facade's U2UE_* variables is converted by the recipe below, Converting a tool, and Appendix B tracks the ones left. u2ue check runs every tool's own selftest.

Where a tool finds the project

A tool reads the project only through u2ue/env.py. need("U2UE_<NAME>") returns the project's value, or REFUSES by name when it is not set: there is no default, because a default is some other game's folder. part(name) gives the toolkit's own folders. The facade exports the project's values to every tool it runs (Project.env(): the project's folders as U2UE_*, the toolkit's as U2UE_PART_*), and u2ue check hands them to every selftest. To run one tool by hand, run it through the facade:

py -m u2ue --project <name> tool <file> [its own options]

A tool kept in another tree finds the toolkit through U2UE_HOME, or refuses.

Converting a tool

Scope: one tool that still names a game's folders. Precondition: the tool has a selftest, or one is written first. Minimal guarantee: run without the facade, the converted tool refuses by name. Success guarantee: the tool reads the project only through u2ue/env.py, and does what it did before. Trigger: a tool names a game's folder.

Converting a tool is a patch, proven like a route:

  1. Replace each literal with need("U2UE_<NAME>") for a project folder and part(name) for a toolkit folder.
  2. Prove the values. Under the project the tool was written for, every literal it replaced resolves to the same value.
  3. Prove the refusal. The converted copy refuses, by name, when it runs without the facade.
  4. Prove the behaviour. Its selftest prints the same output before and after.
  5. Run it through the facade: py -m u2ue --project <name> tool <file>.

A release

Scope: the toolkit's own trees, assembled into one repository by the manifest in u2ue/release.py. Precondition: the target folder is empty, or a checkout an earlier release wrote. Minimal guarantee: a secret in a shipped file refuses the whole release, and every file left out is named with its reason. Success guarantee: the repository holds exactly what the manifest ships, and release --check says it is current. Trigger: the owner wants the toolkit's current state in its repository.

  1. See what would ship. py -m u2ue release --to <DIR> --dry prints what would be written and deleted, what is left out and why, and the public-readiness count (shipped files that still name a game, a person or a machine path). It writes nothing.
  2. Assemble it. py -m u2ue release --to <DIR> writes the repository. A secret refuses it (exit 2), and so does a folder that an earlier release did not write.
  3. Prove it is current. py -m u2ue release --check --to <DIR> exits 1 when the folder differs from what the manifest writes.
  4. Prove it runs from a fresh clone. Clone the repository, point U2UE_TOOLKIT_ROOT at the clone, and run dotnet test u2ue/runtime/U2ue.Runtime.Tests and py -m u2ue.verbs.release --selftest there.
  5. Leave the history to the owner. The verb commits and pushes nothing: the repository's history, its remote and whether it is public are the owner's decisions.

The work packages: every tool a port runs

Every tool a port runs belongs to one of fifteen work packages, by the part of the port it serves. The packages come from a survey of the tools on the reference port's disk (u2ue/README.md): each tool's entry point, its own selftest's result, and its bindings (the paths and names a second game would have to change). The facade WRAPS these tools and never rewrites them, so each still runs by hand. Each package's tools are listed in the chapter that uses them:

# package where they are described
1 the game model and its seams Chapter 5, "The model's tools"
2 Unity IR extraction (effects) Chapter 6, "The effect readers: the IR extraction tools"
3 the effect converter this chapter, "The converter's tools"
4 materials and shader parents this chapter, "Material parents: the tools"
5 meshes, textures and sprite art Chapter 6, "Meshes, textures and sprite art: the tools"
6 scenes and maps Chapter 6, "The scene tools"
7 UI and HUD Chapter 6, "The UI tools"
8 measurement: the Unity windows and the Niagara probes Chapter 8, "The measurement tools"
9 Unreal runs Chapter 3, "The Unreal-run tools"
10 queues and the pause protocol Chapter 3, "Unattended queues and the pause protocol"
11 read-back and checks Chapter 10, "Read-back and checks: the tools"
12 proofs and flips this chapter, "Proofs and flips: the tools"
13 photos and contact sheets Chapter 10, "Photos and contact sheets: the tools"
14 game integration: the effect ledger Chapter 5, "Game integration: the effect ledger"
15 the acceptance report Chapter 10, "The acceptance report: the tools"

How the survey was measured

Three tools in u2ue/survey/ make the survey. Re-run them when the tools change:

  • Inventory: pt1_inventory.py opens every tool file in the toolkit's tool folders and the model gates, and records each one's first docstring line, its usage lines and its bindings. A binding is found by one regular expression per kind over the file's source, so it counts the files that NAME a path or a name; it does not prove that every use is a dependency.
  • The core: pt1_callgraph.py follows what the drivers call (the queues, the trial chain, the Unity window and its launcher, the report builder), then what those call, until a pass names nothing new: the core chain a port runs. The packages are that core plus the model gates, the UI converter and the art steps, which the effect drivers do not call.
  • Selftests: pt1_selftests.py runs every core tool's OWN selftest (only the ones its file defines - none invented), offline, at below-normal priority. A selftest whose body writes was read first, and writes only to a temporary folder. It is also the registry u2ue check --only selftests runs (the selftest recipe above). The ones deliberately not run are listed below, each with its reason.

What the survey found

Measured on the reference port's tools (2026-10-13). Each finding is a trap any port's tooling can fall into:

  • A selftest no driver runs rots unseen. No driver ran any selftest, and three were broken: shuriken_size.py, v4_msg_gate.py (which reads the writes Unreal refused the converter, as saved inside each package; a bare --selftest compared a package with itself) and the port's adapter gate (below). u2ue check --only selftests runs them all, your project file's own included.
  • Orchestration kept in a temporary folder is one clean-up from gone. 123 of 143 driver-shaped files lived only in a session's temporary folder, with no copy in any repository. Keep every driver in a repository; the reference port keeps its drivers in the lane part.
  • A zero is believed only when the instrument finds the known positive. v4_msg_gate.py --dir read 0 refused converter writes over all 672 saved effect systems. The zero was trusted because the same reader parsed 1,992,662 exports there (none unreadable) and finds the 80 refusals of a package known to hold them.
  • A gate that cannot reach a verdict must say so. The adapter gate could not reach one for eleven days, and nothing said so. One leg held copies another change had removed, so it could only answer BLOCKED; another built a check project missing two references the real project had gained (210 false errors). Both were repaired with plants; the gate then ran, and was red on one real thing.
  • Tools spread over several repositories need one place that names them: u2ue/tools.py names each part's folder once (above, "Where the toolkit's parts live").

Which tool each verb runs

The facade runs each tool with the project's U2UE_* variables (project.py, tools.py), read from the project's JSON file in u2ue/projects/. The Unreal verbs share u2ue/verbs/_ue.py: host_busy, native_path_ok, run_ps (one effect-tools PowerShell script with the project's environment, below normal priority), build_record and built_systems (the record <records>/u1e-build-<tag>.json and its BUILT systems), and clean_env: the project's environment with every inherited U1E_* and VFXPORT_* variable removed and named, so a verb runs the project's defaults, never a switch left over in the shell. The effect verbs run these tools:

  • extract (verbs/extract.py): the guid index (t1_guid_index.py), then the keys - the reference port's own resolver (u1e_resolve.py), or the generic particle_prefabs source in keys.py (every prefab holding a ParticleSystem in its own file or through a nested instance or variant, each keyed unity.prefab.<guid>) - then u1e_ir.py. It strips any inherited U1E_* or VFXPORT_* switch first, and exits 1 unless every READ key came out as an IR file or a NAMED refusal, every IR parses, and every Assets/... path an IR names exists in THAT project's tree. A unity. key is read with Unity's own spawn rules (playOnAwake; a sub-emitter's parent) and no game timing - ABSENT, and named - and its scripts are listed as not read.
  • check (verbs/check.py): every tool's own selftest, the two field gates for the project (yaml_field_gate over its IR, ir_field_gate for the reader against the converter), the measured rules' Unity versions (facts) and the model's layer and host gates (model) - a gate nobody runs goes red unseen.
  • report (verbs/report.py): report_build.py over the project's records (U2UE_EFFECTS_DIR, U2UE_RECORDS_DIR). Proven on the reference port: the patched tools with no facade give the same page byte for byte (bar its generation time), and through the facade the same page plus its title.
  • build, read, photo (verbs/build.py, verbs/read.py, verbs/photo.py, sharing verbs/_ue.py): the asset-name table and fx17_build.ps1 (record <records>/u1e-build-<tag>.json); u1e_color_size_readback per frame (<records>/rb_<tag>_<N>.json); u1e_fx_photo then u1e_photo_sheet. Each refuses while the Unreal host is busy (the adapter's host_busy) and refuses a Git Bash launch (Chapter 13).

The effect tools read the project's paths through one patch, pt23_chain_patch.py in the lane part, proven like a route (the tool-conversion recipe above): every binding equals the old literal with no facade variables set and under the reference project, and a sample built through the facade equals its records.

What a second project found in the readers

Measured 2026-10-13 (u2ue/README.md). A second, unrelated game is the test that the readers are not tuned to one project:

  • The reference project through the facade is byte-identical: a 21-key sample covering every kind of prefab the reader handles gave 20 IR files equal to a direct run and to the live IR; the summary rows were equal, and the one refusal the same.
  • The second game (Unity 2021.3.21f1): 3,229 prefabs, 60 keys (52 hold a ParticleSystem, 8 only through nesting), 56 IR files with 189 emitters, 4 refused by name, 0 dropped, 0 foreign paths; 3 more prefabs UNKNOWN (they nest assets the project lacks). It found three reader gaps the reference port never exercised, and each was fixed with a selftest case and a mutant that must break it: the 2018.1-2018.2 legacy Prefab record (m_SourcePrefab {fileID: 0}, m_IsPrefabAsset), nested MODEL instances (an imported model file, such as an FBX, placed inside a prefab: left out and named, refused when a ParticleSystem depends on one) and m_RemovedComponents (applied). Of the 4 refused, 3 are modifications aimed at objects inside a model that was left out (Unity derives a model's object ids internally, which cannot be proven from the files) and 1 is a script field the source's data lacks.
  • Every shader a project's effects use is named. The guid index covers a project's PACKAGES too: after Assets, its embedded Packages/, then Library/PackageCache, pruning a folder starting . or ending ~ as Unity's importer does. So URP's particle and lit shaders resolve. Unity's BUILT-IN shaders (guid 0000000000000000f000000000000000, which are not files) are named off the project's own Editor's Resources/unity_builtin_extra by u1e_builtin_names.py, which walks that SerializedFile by its own type trees. A project opts in with unity.editor.
  • An older format meets no silent default. A census of every field emitter_ir looks for and does not find, over both projects, found two kinds of new miss: field renames, now read from the other name, and Unity 5-era documents whose newer fields reach the IR as None. Those are ABSENT, and the converter then has to name them.
  • yaml_field_gate runs on any project (U2UE_UNITY_ROOT, U2UE_IR_DIR). It found the second game's unread light-module fields. It also found the reference port's own whole-game corpus RED: three excuses written on a sample of 51 prefabs ("0 on every fired emitter") were false on 655 (ring buffers, unscaled time, renderer priority). The reader reads all of them now; what it puts in the IR is held by ir_field_gate, which names the fields the converter must port or name. An excuse measured on a sample is a claim about the sample. Since 2026-10-20 the gate keys a field by its module path (it matched a bare name before, and passed every enabled by-speed module), and it fails both projects again on fields no reader reads yet: the by-speed modules, the light module's colour, range and intensity switches, and the collision module's quality.

Not run, and why

  • plugin_sync_gate.py --selftest corrupts and restores the INSTALLED plugin DLL in the game's live Unity project, and a DLL change under an open editor is a domain reload nobody asked for. Run it by hand when that editor is closed.
  • A project's own not_run rows (the selftests block of its project file) each print their measured reason. A publish gate whose selftest launches Unreal belongs there, because one headless Unreal runs at a time.
  • Read-dependent plants (--plant* on the read-back checks) need a trial's own read pair. The trial chain runs each one in every trial, never against an older read (Chapter 10).

The tools no driver reaches

A tool outside the core chain stays where it is, because each finished step's tools are its evidence. Chapter 21's generated inventory counts every folder's tools, how many are in the core chain a port runs, and how many carry a selftest.

The converter's tools

In this chapter's tables, "check" says whether u2ue check --only selftests runs the tool's own selftest; "a plant per trial" means the trial's judges hold the tool's output and must refuse their plants.

tool part what it does check
build_niagara.py vfxport the converter: one IR emitter into Niagara stack writes, imported by u1e_build.py inside a headless Unreal run a plant per trial
shuriken_size.py vfxport the Shuriken to Niagara SIZE rule, with no engine in it yes
subframe_rule.py vfxport the frame a Birth or Death sub-emitter child emits its shape in, re-derived from its bake at build time (Chapter 8) yes
cube_remap.py vfxport Unity's cube faces onto the faces of an Unreal TextureCube that samples, along the converted direction, the texel Unity samples yes
u1e_slots.py effects_tools which material slots of an emitter Unity DRAWS, and which of them point at an asset the project lacks yes

Every value the converter cannot read is named SUBSTITUTED or ABSENT in the build record, never defaulted. A second game brings nothing project-specific to the rules themselves, only its content root and its IR folder.

Inside the converter

vfxport/build_niagara.py turns one IR emitter into Niagara stack writes through Unreal's FXConverterUtilitiesLibrary. build_emitter is the loop over the twenty stages (Chapter 7 lists them, in the order Unity's own modules run); each stage is a _stage_* function. The state one stage hands to a later one lives on ONE object, _EmitterBuild; everything else is a local of its stage. Each stage calls a family of helpers named for what they write (build_frame_shape, build_frame_mesh_renderer, write_collision, sub_emitter_plan, ...), and a rule measured in Unity is re-derived from its bake at build time by its judge (alignmesh_rule(), ringbuffer_check.rules()), so a rule that stops holding stops the build instead of drawing wrongly.

Prove any refactor of the converter with whole_trace.py. The stages were split out of one 1,430-line function with 221 locals by vfxport/split_build_emitter.py. It finds the locals a stage reads but an earlier stage set, and only those go on the state object. whole_trace.py proved the split: 0 calls differ, 0 exceptions. A new route lands in one stage, behind its switch, and its offline proof ("Proofs and flips", below) names exactly the emitters it touches.

Material parents: the tools

Each Unity material becomes an Unreal material instance over a HAND-PORTED parent, one parent per distinct Unity shader family. The blend is read as a NUMBER from the .mat, textures are imported with Unity's own alpha and settings, and anything built is reused only when nothing it was built from changed. The families below are vendor asset packs (the ones the reference port used), so their parents are reusable by any game that uses those packs.

The largest family, a vendor's uber shader graph, done in full (scene_tools):

tool what it does check
vm1_read_shadergraph.py reads the .shadergraph (one JSON record per object, no Unity) and emits its complete surface: every property a .mat overrides, every node type the parent must reproduce -
vm1_read_materials.py the REAL numbers off every .mat that uses the shader - the set the game fires, and the superset on disk, both reported, because the difference matters for an INERT claim yes
vm1_hlsl.py the graph's arithmetic as the HLSL of the parent's Custom node (an Unreal material node that runs shader code written by hand): every line names the ShaderGraph node it came from, and every formula is the one Unity's own node source generates -
vm1_hlsl2.py the same arithmetic split across three Custom nodes, so that no texture is sampled inside a Custom node -
vm1_tex3.py the eleventh null case on a texture-override blocker, and the first whose control could FAIL -
vm1_author.py builds the parent, and one material instance per Unity .mat with the numbers READ off it -
vm1_account.py every surface the graph exposes marked APPLIED, INERT with the arithmetic that makes it inert, or ABSENT with the reason; exits 1 unless the unaccounted count is 0 (the material-family recipe above) yes

A null result is evidence only when its control could have come out the other way: the ten null cases before vm1_tex3.py had ruled out a cause against a control that could not fail.

The other families (effects_tools), each one parent and one instance per material:

tool the Unity shader it ports
u1e_hovl.py Hovl Studio's HS_Blend_CG Shader Graph
u1e_hsblenddistort.py Hovl Studio's HS_BlendDistort Shader Graph
u1e_hsdissolve.py Hovl Studio's DissolveNoise, a hand-written CG shader
u1e_hselectricity.py Hovl Studio's Electricity, a hand-written CG shader
u1e_hstwosides.py Hovl Studio's HS_Blend_TwoSides Shader Graph
u1e_ubercube.py, u1e_ubercube_hlsl.py Piloto Studio's Uber Cubemap Shader Graph (a parent and its opaque twin; the HLSL of its Custom nodes)
u1e_ubermatcap.py, u1e_ubermatcap_hlsl.py Piloto Studio's Uber Matcap Shader Graph (likewise)
u1e_pilototoon.py Piloto Studio's PilotoToon Mobile Shader Graph
u1e_warp.py Piloto Studio's Piloto Warp Shader Graph
u1e_vefects.py the Vefects Pixel Craft flipbook shaders, one parent per Unity shader
u1e_legacyparticle.py Unity's BUILT-IN particle material

Textures and the checks around them (effects_tools unless named):

tool what it does check
u1e_blends.py the blend factor a Unity .mat does NOT serialize, from what Unity was MEASURED to use yes
u1e_alpha.py each effect texture's ALPHA as Unity's importer makes it, written as a file Unreal imports as it is -
u1e_psd.py the MERGED image of a Photoshop file (PSD or PSB), read straight off the file yes
u1e_psdtex.py that PSD conversion, run outside Unreal -
u1e_material_errors.py the REAL material compile errors in an Unreal log yes
l1_skybox_to_equirect.py (scene_tools) a skybox's cubemap turned into a lat-long .hdr, from the one texture its material actually assigns -
u1e_cube_probe.py which texel an Unreal TextureCube samples along a direction - the Unreal half of the cube rule -
u1e_vcspace.py Unity's "Apply Active Color Space" on every Niagara-facing parent -

Proofs and flips: the tools

These are the tools behind the converter-route recipe above: the trace proof, the flip and the audit. u2ue/routes.py reads the flip table and flip_audit's list into Route objects: ON when EVERY file that reads the switch reads it default on, DELIBERATELY OFF when flip_audit names what it waits on, OFF otherwise. Pillar 3 fails a cycle in which the converter's line count went up (a trend check, Chapter 14), which is why a flip adds no line to it.

tool part what it does check
whole_trace.py vfxport the WHOLE engine-call trace of every active emitter of all IRs, one converter file against another (Chapter 9) yes
burst_trace.py vfxport the same trace for every emitter whose emission carries a burst, the committed converter against the working one yes
converter_trace_gate.py vfxport does the working converter still write EXACTLY what a committed one wrote, for every existing route yes
unreachable_gate.py vfxport refuses Python source with a statement that can never run (one after a return, raise, continue or break in the same block): deleting one if line once left a block silently dead yes
absentdraw_proof.py lane a route's offline proof written as a script: the reference converter at a commit, the working copy with the switch OFF and ON, and the changed emitters PREDICTED before the working copy runs -
patch_flip_defaults.py vfxport flips VERIFIED switches to default ON - each os.environ.get("NAME", "0") == "1" becomes os.environ.get("NAME", "1") != "0", so NAME=0 still switches it off - with the evidence held once, as a row of its TABLE -
flip_audit.py lane every switch a trial set by hand: flipped, or named DELIBERATE_OFF with its reason -
fx9_space_gate.py effects_tools a sub-emitter's space cases on a moved and turned component, each child taken on its first frame against its parent's world point -
py -m u2ue --project <name> tool whole_trace.py REF.py WORK.py [--on VFXPORT_X --expect-only KEY:PSFILEID]   # the trace proof
py vfxport/patch_flip_defaults.py --list      # the flip table
py vfxport/patch_flip_defaults.py <ROUTE>     # the flip, with its TABLE row

A second game supplies nothing here: the proofs are the converter's.

19. The facade: detailed requirements

Who this is for: the reviewer checking what a verb promises, and the toolkit developer changing one - every verb as a requirement, with the options it takes, the refusals it can give, its exit values and the checks that hold it. After it you can check a verb's behaviour against its code without reading the code first.

The facade is the toolkit's one entry point, py -m u2ue. Each verb it answers is one requirement on the toolkit. This chapter states each requirement and everything the code says about it, read from the verb's own source on every build, so the page and the code cannot drift apart.

How each requirement is read

  • Requirement: the verb's row in the registry (u2ue/verbs/__init__.py), the single list the command line, find, the verb list and this manual all read. A verb added anywhere else would be invisible, which is why there is only one list.
  • Implemented by: the verb's module and its public functions. Every verb module exposes run(p, argv), where p is the loaded project (or nothing, for a verb that needs none).
  • Inputs: every option the module's argument parser declares, with its help text, read from the code. A verb that reads its arguments by hand lists the options it compares.
  • Refuses: every refusal message the module can print or raise, with its line. A refusal is the toolkit's answer when an input is missing or wrong: it names the cause and stops, and never substitutes a default. A message that names a machine path or the reference game is shown with that part replaced by <path> or <game>. Those are hard-wired sites the core is shedding (pillar 7, Chapter 14).
  • Exits: the literal exit values in the module. Across the facade, 0 is success, and 2 is a refusal before any work starts (an unknown verb, a project that does not load, or a verb that needs a project run without one). Each verb's own meaning of 1 is in its usage text (Chapter 20).
  • Verified by: the verb's selftest in the selftest registry (u2ue/survey/pt1_selftests.py), with the verdict of its last run. ABSENT means the registry runs no selftest for that verb. The gap is listed here instead of being hidden. Each run's date is in u2ue/survey/pt1_selftests.json. This page carries only the verdict, so a cycle that re-runs the selftests leaves it current, and a verdict that changes makes it stale.
  • Exercised by: the use-case steps (Chapter 17) whose proof command runs the verb. A verb that no step runs is still a requirement, just one the model does not exercise yet.

35 verbs, each read from its module's own source: 27 with a selftest in the registry, 31 run as the proof of a use-case step. A requirement is numbered FR-<verb>; its inputs, refusals and exits are the code's, line by line.

requirement the verb needs a project selftest proves use-case steps
FR-FIND find no passes (exit 0) 2
FR-ESTIMATE estimate no passes (exit 0) 1
FR-PORT port yes passes (exit 0) 1
FR-INFO info yes ABSENT 4
FR-INVENTORY inventory yes passes (exit 0) 8
FR-UML uml yes passes (exit 0) 3
FR-SCAFFOLD scaffold yes passes (exit 0) 2
FR-SLICE slice yes registered, never run 4
FR-CITE cite yes registered, never run 0
FR-MUTATE mutate yes registered, never run 0
FR-REQ req yes registered, never run 0
FR-LOGIC logic yes passes (exit 0) 2
FR-DATA data yes passes (exit 0) 2
FR-SHEAR shear yes passes (exit 0) 1
FR-SCENE scene yes passes (exit 0) 5
FR-PARITY parity yes passes (exit 0) 3
FR-DIGEST digest yes passes (exit 0) 2
FR-HOST host yes registered, never run 1
FR-UI ui yes passes (exit 0) 2
FR-WINDOW window yes passes (exit 0) 12
FR-TRIAL trial yes passes (exit 0) 2
FR-CONFORM conform yes passes (exit 0) 4
FR-JUDGE judge yes ABSENT 1
FR-EXTRACT extract yes ABSENT 3
FR-CHECK check yes ABSENT 8
FR-BUILD build yes ABSENT 2
FR-READ read yes ABSENT 2
FR-PHOTO photo yes passes (exit 0) 2
FR-REPORT report yes ABSENT 3
FR-METRICS metrics yes ABSENT 3
FR-TEMPO tempo yes passes (exit 0) 1
FR-CYCLE cycle yes passes (exit 0) 12
FR-TOOL tool yes passes (exit 0) 1
FR-RELEASE release no passes (exit 0) 3
FR-BLUEPRINT blueprint no registered, never run 0

FR-FIND find

Requirement (the registry row, u2ue/verbs/__init__.py): search everything the toolkit holds: verbs, adapters, tools, docs, measured rules, converter stages, routes.

Implemented by u2ue/verbs/find.py (76 lines; public: run, selftest). Needs a project: no. Its usage text is in Chapter 20.

Inputs:

option for what it is notes
words all - nargs '*'
--kind all comma-separated: ... -
--top all results shown per kind default 6
--selftest all - a flag

Refuses: no refusal message of its own; it stops with the exit of the tool it runs.

Exits: 0, 1, 2.

Verified by: py -m u2ue find --selftest - last run passes (exit 0) (u2ue/survey/pt1_selftests.json).

Exercised by: UC-06 step 3, UC-13 step 2.

FR-ESTIMATE estimate

Requirement (the registry row, u2ue/verbs/__init__.py): what porting a Unity project will cost in model tokens: its code and assets read, times rates measured on a real port, with the cache split, the list cost and the confidence.

Implemented by u2ue/verbs/estimate.py (229 lines; public: M, render, run, selftest). Needs a project: no. Its usage text is in Chapter 20.

Inputs:

option for what it is notes
--unity all the Unity project's root folder (the one holding Assets/); default the project's unity.root -
--roots all the game's own code folders, comma-separated, relative to the Unity root (default: the project's code.roots, else every folder under Assets) -
--exclude all folders that are not the game's to move, comma-separated, relative to the Unity root - a vendored library is replaced, not ported (the subfolder lines show where the lines are) -
--model all the model the price is read for (u2ue/basis/prices.json) default 'claude-opus-5-5'
--json all also write the whole estimate as JSON here -

Refuses (2 messages, as the code writes them):

  • line 115: REFUSED: --unity <Unity project root> names the project to estimate (or --project <name>)
  • line 123: REFUSED: %s

Exits: 0, 2. Its docstring: The basis (u2ue/basis/tokens.json) is written by u2ue/survey/token_basis.py from a project's own records. Exit 0 = estimated;

Verified by: py -m u2ue.verbs.estimate --selftest - last run passes (exit 0) (u2ue/survey/pt1_selftests.json).

Exercised by: UC-11 step 1.

FR-PORT port

Requirement (the registry row, u2ue/verbs/__init__.py): the whole port as one command: every stage in order, each read from its own records; runs what a verb can, stops with one question where a person, the AI or an editor is needed.

Implemented by u2ue/verbs/port.py (162 lines; public: render, run, selftest). Needs a project: yes. Its usage text is in Chapter 20.

Inputs:

option for what it is notes
--run all run the AUTOMATIC stages that are TODO, in order; a RED stage holds back only the stages that wait on it a flag
--with-unreal all with --run: also the stages that launch a headless Unreal a flag

Refuses (1 messages, as the code writes them):

  • line 69: REFUSED: %s

Exits: 0, 1, 2. Its docstring: Exit 0 = nothing left (every stage DONE, or ABSENT / UNCHECKED and said); 1 = something is left, the next action printed;

Verified by: py -m u2ue.verbs.port --selftest - last run passes (exit 0) (u2ue/survey/pt1_selftests.json).

Exercised by: UC-11 step 3.

FR-INFO info

Requirement (the registry row, u2ue/verbs/__init__.py): every path the project names, OPENED; its adapter.

Implemented by u2ue/verbs/info.py (15 lines; public: run). Needs a project: yes. Its usage text is in Chapter 20.

Inputs: read by hand from its arguments; it takes none by name.

Refuses: no refusal message of its own; it stops with the exit of the tool it runs.

Exits: the exit of the tool it runs. Its docstring: u2ue info - every path the project names, OPENED (exit 1 when an INPUT is missing), its adapter and its key source.

Verified by: ABSENT - the selftest registry runs no selftest of this verb.

Exercised by: UC-02 step 4, UC-11 step 2, UC-18 step 1, UC-20 step 1.

FR-INVENTORY inventory

Requirement (the registry row, u2ue/verbs/__init__.py): the game's own C#, type by type: Unity API by family, pure rules, the frame order (no editor runs).

Implemented by u2ue/verbs/inventory.py (1009 lines; public: MvcCensus, blank, census_report, execution_order, inventory, parse_field, pointer_problems, report, run, run_mvc, scan_file, selftest, split_bases, split_type, survey, type_members, type_tree, types_of, write_sites). Needs a project: yes. Its usage text is in Chapter 20.

Inputs:

option for what it is notes
--survey all - a flag
--roots all - -
--out all - -
--selftest all - a flag
--mvc all - a flag

Refuses (1 messages, as the code writes them):

  • line 240: u2ue inventory: code root %s is not a folder

Exits: 0, 2.

Verified by: py -m u2ue.verbs.inventory --selftest - last run passes (exit 0) (u2ue/survey/pt1_selftests.json).

Exercised by: UC-11 step 2, UC-14 step 2, UC-15 step 1, UC-16 step 1, UC-16 step 3, UC-16 step 8, UC-18 step 2, UC-18 step 3.

FR-UML uml

Requirement (the registry row, u2ue/verbs/__init__.py): the game's class model off its own code roots (and its model once scaffolded): extract, mermaid, where, ask.

Implemented by u2ue/verbs/uml.py (156 lines; public: command, roots, run, selftest, usecases). Needs a project: yes. Its usage text is in Chapter 20.

Inputs: read by hand from its arguments - --doc, --selftest.

Refuses (1 messages, as the code writes them):

  • line 81: REFUSED: ...

Exits: 2.

Verified by: py -m u2ue.verbs.uml --selftest - last run passes (exit 0) (u2ue/survey/pt1_selftests.json).

Exercised by: UC-14 step 3, UC-15 step 1, UC-16 step 2.

FR-SCAFFOLD scaffold

Requirement (the registry row, u2ue/verbs/__init__.py): the engine-free model a game's rules move into: created, declared in the project file, built and gated.

Implemented by u2ue/verbs/scaffold.py (216 lines; public: files_for, model_block, run, scaffold, selftest). Needs a project: yes. Its usage text is in Chapter 20.

Inputs:

option for what it is notes
--name all the model's name: .Core, .Core.Tests required
--dir all the folder the two projects go in (outside the Unity Assets tree) required
--dry all - a flag

Refuses: no refusal message of its own; it stops with the exit of the tool it runs.

Exits: 0, 2. Its docstring: both projects and runs that check. Exit 0 = the model exists, compiles, and its gates pass on it; 1 = a build or a gate failed;

Verified by: py -m u2ue.verbs.scaffold --selftest - last run passes (exit 0) (u2ue/survey/pt1_selftests.json).

Exercised by: UC-15 step 6, UC-16 step 4.

FR-SLICE slice

Requirement (the registry row, u2ue/verbs/__init__.py): every check one slice of a logic refactor must pass before it lands: builds, tests against a recorded baseline, the model gates, Unity compiled headlessly (optionally from an overlay), parity.

Implemented by u2ue/verbs/slice.py (2189 lines; public: RealEditorWorld, run, selftest). Needs a project: yes. Its usage text is in Chapter 20.

Inputs: read by hand from its arguments - --baseline, --battle, --because, --compare, --deadline-s, --handed-over, --ignore-fields, --ignore-kinds, --ignore-rows, --mode, --on, --overlay, --seed, --selftest, --undo-first-move, --undo-mid-walk.

Refuses (2 messages, as the code writes them):

  • line 292: u2ue slice %s: REFUSED - %s
  • line 313: u2ue slice: REFUSED - %s

Exits: 0, 1, 2. Its docstring: Exit 0 = every check passed (the slice may land) / the landing PASSED; 1 = a check failed (each named, with its first error) / the

Verified by: py -m u2ue.verbs.slice --selftest - last run registered, never run (u2ue/survey/pt1_selftests.json).

Exercised by: UC-14 step 1, UC-14 step 4, UC-14 step 5, UC-14 step 7.

FR-CITE cite

Requirement (the registry row, u2ue/verbs/__init__.py): every File.cs:N breadcrumb in the model's comments held to the code it names: a quoted one HOLDS, MOVED (to the line it is on now) or BROKEN; one with no quote counted.

Implemented by u2ue/verbs/cite.py (116 lines; public: run, selftest). Needs a project: yes. Its usage text is in Chapter 20.

Inputs:

option for what it is notes
--list all every citation with that verdict one of CitationCheck.VERDICTS

Refuses (1 messages, as the code writes them):

  • line 39: REFUSED: %s names no model.root / model.scan - the folders whose comments cite the game's code

Exits: 2. Its docstring: Exit 0 = no quoted citation is BROKEN; 1 = one is (each named); 2 = refused (the project names no model). A MOVED citation is

Verified by: py -m u2ue.verbs.cite --selftest - last run registered, never run (u2ue/survey/pt1_selftests.json).

Exercised by: no use-case step runs it as its proof.

FR-MUTATE mutate

Requirement (the registry row, u2ue/verbs/__init__.py): would any test notice if a rule changed: each mutation a file lists applied to a fresh copy of what the project file declares, the tests run there - CAUGHT, SURVIVED, COMPILE-BREAK, NO-RESULT or ANCHOR-MISS, ending MUTANTS NOT CAUGHT n of m; the project's own files never written.

Implemented by u2ue/verbs/mutate.py (99 lines; public: run, selftest). Needs a project: yes. Its usage text is in Chapter 20.

Inputs:

option for what it is notes
spec all - -
--only all - -
--keep all - a flag

Refuses (1 messages, as the code writes them):

  • line 33: u2ue mutate: REFUSED - %s

Exits: 2. Its docstring: Exit 0 = every mutation CAUGHT and the untouched copy green again after; 1 = MUTANTS NOT CAUGHT n of m with n above 0 - SURVIVED

Verified by: py -m u2ue.verbs.mutate --selftest - last run registered, never run (u2ue/survey/pt1_selftests.json).

Exercised by: no use-case step runs it as its proof.

FR-REQ req

Requirement (the registry row, u2ue/verbs/__init__.py): every // REQ: citation in the game's code resolved in the requirement documents its project file names: HOLDS (a line that says something, an id a line starts with, a section the document defines, a folder's entry), TAGGED (one of its tags: no designer requirement, declared) or UNRESOLVED (to the designer).

Implemented by u2ue/verbs/req.py (99 lines; public: run, selftest). Needs a project: yes. Its usage text is in Chapter 20.

Inputs:

option for what it is notes
paths all - nargs '*'
--unresolved all - a flag

Refuses (2 messages, as the code writes them):

  • line 31: u2ue req: REFUSED - no paths given and the project names no requirements.roots
  • line 35: u2ue req: REFUSED - %s

Exits: 1, 2. Its docstring: Exit 0 = every citation holds or is tagged; 1 = one or more UNRESOLVED, or no citation at all under the paths (a check that read

Verified by: py -m u2ue.verbs.req --selftest - last run registered, never run (u2ue/survey/pt1_selftests.json).

Exercised by: no use-case step runs it as its proof.

FR-LOGIC logic

Requirement (the registry row, u2ue/verbs/__init__.py): where this project's logic port stands: each u2ue-logic skill step judged by its own DONE WHEN, read from its records.

Implemented by u2ue/verbs/logic.py (100 lines; public: run, selftest). Needs a project: yes. Its usage text is in Chapter 20.

Inputs: read by hand from its arguments - --selftest.

Refuses (1 messages, as the code writes them):

  • line 86: REFUSED: <the cause>

Exits: 0, 2.

Verified by: py -m u2ue.verbs.logic --selftest - last run passes (exit 0) (u2ue/survey/pt1_selftests.json).

Exercised by: UC-11 step 4, UC-14 step 8.

FR-DATA data

Requirement (the registry row, u2ue/verbs/__init__.py): a component's or ScriptableObject's serialized values off a scene / prefab / asset, overrides applied (no editor runs).

Implemented by u2ue/verbs/data.py (208 lines; public: leaves, read, run, script_guid, selftest). Needs a project: yes. Its usage text is in Chapter 20.

Inputs:

option for what it is notes
--from all - -
--script all - -
--class all - -
--out all - -
--tsv all - -
--no-expand all - a flag
--selftest all - a flag

Refuses (3 messages, as the code writes them):

  • line 46: u2ue data: %d scripts named %s.cs in the guid index%s
  • line 81: u2ue data: %d YAML documents of %s did not parse (%s)
  • line 104: u2ue data: class %r is neither a class id nor one of %s

Exits: 2.

Verified by: py -m u2ue.verbs.data --selftest - last run passes (exit 0) (u2ue/survey/pt1_selftests.json).

Exercised by: UC-15 step 5, UC-18 step 4.

FR-SHEAR shear

Requirement (the registry row, u2ue/verbs/__init__.py): the scene nodes Unreal cannot place as Unity does (a sheared transform chain), with the error in cm.

Implemented by u2ue/verbs/shear.py (196 lines; public: census, gltf_chains, run, selftest, yaml_chains). Needs a project: yes. Its usage text is in Chapter 20.

Inputs:

option for what it is notes
--gltf all - -
--from all - -
--no-expand all - a flag
--json all - -
--eps all - default 1e-06
--selftest all - a flag

Refuses (3 messages, as the code writes them):

  • line 34: u2ue shear: node %d carries a matrix (not TRS) - read it as a matrix first, never guessed
  • line 48: u2ue shear: node %d names mesh %s and the file declares %d - a malformed glTF
  • line 86: u2ue shear: transform %s is named as a father and is not in %s

Exits: 0, 2.

Verified by: py -m u2ue.verbs.shear --selftest - last run passes (exit 0) (u2ue/survey/pt1_selftests.json).

Exercised by: UC-12 step 1.

FR-SCENE scene

Requirement (the registry row, u2ue/verbs/__init__.py): a Unity scene as an Unreal level: export (in a window), import, readback, and the fidelity gate against its own baseline.

Implemented by u2ue/verbs/scene.py (168 lines; public: run, scene_of, selftest, unity_scene_path). Needs a project: yes. Its usage text is in Chapter 20.

Inputs: read by hand from its arguments - --content, --dir, --dry, --json, --no-parity, --out, --scene-dir, --selftest, --unity-scene.

Refuses (5 messages, as the code writes them):

  • line 61: u2ue scene: REFUSED - ...
  • line 71: u2ue scene: REFUSED - the content root %r is not under /Game/
  • line 88: u2ue scene export: REFUSED here - the export runs in the game's own Unity Editor, which a verb never touches. A window
  • line 95: u2ue scene %s: REFUSED - the Unreal host is busy: %s
  • line 100: u2ue scene %s: REFUSED - run from native PowerShell (this PATH lacks 'Program Files\dotnet\' with its trailing backslash: UnrealSharp cannot find .NET)

Exits: 0, 1, 2. Its docstring: files and the scene's OWN measured baseline (/fidelity-baseline.json); exit 1 the moment one moves, 2 when an

Verified by: py -m u2ue.verbs.scene --selftest - last run passes (exit 0) (u2ue/survey/pt1_selftests.json).

Exercised by: UC-12 step 2, UC-12 step 3, UC-12 step 4, UC-12 step 5, UC-12 step 6.

FR-PARITY parity

Requirement (the registry row, u2ue/verbs/__init__.py): the game's rules on every runtime they run on, compared by float bits with a characterised allowance.

Implemented by u2ue/verbs/parity.py (78 lines; public: run, selftest). Needs a project: yes. Its usage text is in Chapter 20.

Inputs: read by hand from its arguments - --characterise, --dir, --require, --selftest.

Refuses: no refusal message of its own; it stops with the exit of the tool it runs.

Exits: 2. Its docstring: value or a wider gap stays red. Exit 0 agree, 1 a row differs, 2 refused (a required report missing, or digest versions differ).

Verified by: py -m u2ue.verbs.parity --selftest - last run passes (exit 0) (u2ue/survey/pt1_selftests.json).

Exercised by: UC-15 step 7, UC-16 step 9, UC-16 step 10.

FR-DIGEST digest

Requirement (the registry row, u2ue/verbs/__init__.py): the game's rule cases answered with no engine: on CoreCLR (Headless) and on that Unity's own Mono (UnityMono).

Implemented by u2ue/verbs/digest.py (492 lines; public: DigestError, FixtureProject, built_for_unity, fact_for, faithful, model_refs, mono_home, on_coreclr, on_mono, rows, run, run_cases, selftest, selftest_reference, wants_mono). Needs a project: yes. Its usage text is in Chapter 20.

Subcommands: faithful, run.

Inputs:

option for what it is notes
--entry run - -
--cases run - nargs '+'
--refs run - nargs '*'
--dir run - -
--editor run the Unity install whose Mono runs the cases (else the project's unity.editor) -

Refuses (3 messages, as the code writes them):

  • line 296: REFUSED: name --dir or the project's parity.dir - where the digests are compared
  • line 304: REFUSED: name --entry and --cases, or the project's unreal.host.digest
  • line 309: REFUSED: %s

Exits: 0, 2. Its docstring: ran, and that digest. Exit 0 = identical; the measurement is written as a conformance bake

Verified by: py -m u2ue.verbs.digest --selftest - last run passes (exit 0) (u2ue/survey/pt1_selftests.json).

Exercised by: UC-15 step 7, UC-16 step 9.

FR-HOST host

Requirement (the registry row, u2ue/verbs/__init__.py): the game's OWN Unreal project, made as a customer makes one: create, install, compile, generate, wire, publish, run.

Implemented by u2ue/verbs/host.py (427 lines; public: game_map, run, run_unreal, selftest). Needs a project: yes. Its usage text is in Chapter 20.

Inputs: read by hand from its arguments - --dry, --quiet, --selftest.

Refuses: no refusal message of its own; it stops with the exit of the tool it runs.

Exits: 0, 2. Its docstring: (and run also by the digest file being written after the run started). Exit 0 = the step proved itself; 1 = it ran and did not;

Verified by: py -m u2ue.verbs.host --selftest - last run registered, never run (u2ue/survey/pt1_selftests.json).

Exercised by: UC-16 step 10.

FR-UI ui

Requirement (the registry row, u2ue/verbs/__init__.py): a Unity UI screen converted to a folder Unreal reads; the generic uGUI / TextMeshPro library's tests.

Implemented by u2ue/verbs/ui.py (120 lines; public: convert_tool, out_refusal, run, selftest). Needs a project: yes. Its usage text is in Chapter 20.

Inputs: read by hand from its arguments - --out, --screen, --selftest.

Refuses (2 messages, as the code writes them):

  • line 50: u2ue ui capture: REFUSED - a capture runs in the project's own Unity Editor in Play mode (uGUI's resolved state, TextMeshPro's per-glyph layout): the package's Editor assembly, installed in the project, does it - install
  • line 72: u2ue ui convert: REFUSED - ...

Exits: 2.

Verified by: py -m u2ue.verbs.ui --selftest - last run passes (exit 0) (u2ue/survey/pt1_selftests.json).

Exercised by: UC-17 step 2, UC-17 step 3.

FR-WINDOW window

Requirement (the registry row, u2ue/verbs/__init__.py): ONE Unity measurement window from a data file: idle-gated, owner-stoppable, nothing replaced, md5-held.

Implemented by u2ue/verbs/window.py (1116 lines; public: FakeWorld, RealWorld, Refused, Window, World, md5, run, selftest). Needs a project: yes. Its usage text is in Chapter 20.

Inputs:

option for what it is notes
cmd all - one of ('check', 'run')
spec all - -

Refuses (18 messages, as the code writes them):

  • line 114: no channel file - the probes find the runner's folder only through <project>/UserSettings/U2ue/channel.txt
  • line 118: the spec has no %r
  • line 136: the spec stages %s, and no project root is given to stage it in
  • line 138: a stage is a folder under the project's Assets/, named relative to it: %r
  • line 167: the trigger names the placement %r, which the project's unity.placements does not give (%s)
  • line 176: the spec names probe_src %s, and the project's probes come with the installed package - a reference build is dropped as copies, which unity.probes "package" never does
  • line 180: probe_src %s holds no PROVENANCE.json - nothing unaccounted for goes into the owner's editor
  • line 184: %s names no %r
  • line 187: %s lists %s, which the folder does not hold
  • line 190: the spec's probe(s) %s are not among %s's files
  • line 199: the reference build lists %s, which needs %s - the project's Packages/manifest.json lists none
  • line 206: no probe %s in %s
  • line 525: %s names no unity.probe_dir - the Editor folder a probe is dropped into (never guessed)
  • line 528: %s names no unity.probes - "copy" (each probe dropped in for the window) or "package" (the installed u2ue package holds them); it is %r
  • line 550: REFUSED: %s
  • line 568: REFUSED: ...
  • line 578: REFUSED: no QUIET line from wait_quiet (%r) - not started
  • line 598: REFUSED: %s

Exits: 2. Its docstring: py -m u2ue --project window check every refusal judged now, nothing touched (exit 0 = it would start)

Verified by: py -m u2ue.verbs.window --selftest - last run passes (exit 0) (u2ue/survey/pt1_selftests.json).

Exercised by: UC-04 step 3, UC-08 step 2, UC-10 step 1, UC-10 step 2, UC-10 step 3, UC-10 step 4, UC-10 step 5, UC-10 step 6, UC-10 step 7, UC-10 step 9, UC-10 step 10, UC-13 step 2.

FR-TRIAL trial

Requirement (the registry row, u2ue/verbs/__init__.py): a route's TRIAL in Unreal from a data file: build, resave, read, judge, photos; one Unreal at a time, stoppable.

Implemented by u2ue/verbs/trial.py (1045 lines; public: Exec, FakeExec, PlanExec, RealExec, Refused, Stop, Trial, clean_env, commits, fill, others, preflight, run, selftest). Needs a project: yes. Its usage text is in Chapter 20.

Inputs:

option for what it is notes
cmd all - one of ('plan', 'run', 'stop')
specs all - nargs '*'

Refuses (9 messages, as the code writes them):

  • line 107: the spec has no %r
  • line 113: step %d (%s) runs the built systems with no resave after the build - add {"resave": {}} before it
  • line 118: step %d (read): its env may set only the reader's U1E_RB_* variables, not %s
  • line 121: step %d (resave): "only" takes "built" (the systems this trial built), not %r
  • line 129: the trial builds into the project's content root %s, but the project names no records dir to take its build into
  • line 568: REFUSED: %s
  • line 575: REFUSED: trial %s: %s
  • line 581: REFUSED: ...
  • line 589: REFUSED: %s

Exits: 0, 1, 2.

Verified by: py -m u2ue.verbs.trial --selftest - last run passes (exit 0) (u2ue/survey/pt1_selftests.json).

Exercised by: UC-08 step 3, UC-13 step 4.

FR-CONFORM conform

Requirement (the registry row, u2ue/verbs/__init__.py): data-first conformance over all keys: Unity's particle state (one generic probe) against Niagara's readback, paired by file id.

Implemented by u2ue/verbs/conform.py (1002 lines; public: build_notes, burst_dues, cases_cmd, classes_cmd, classify, deathtick, diff, diff_cmd, drawn_frame, draws_at_random, first_seen, first_seen_unity, fx16_boundary, fx16c_k, gridtick, handles, judge_emitter, judge_id, latest_cmd, probe_clock, run, selftest, unity_side, unreal_side, unreal_sides, within_draws). Needs a project: yes. Its usage text is in Chapter 20.

Subcommands: cases, diff, latest, classes.

Inputs:

option for what it is notes
--name cases - required
--keys cases - -
--times cases - -
--step cases step Unity the way the game steps and read Unreal at the same dt, e.g. 1/60 -
--unity diff - required
--unreal diff - required
--report diff - -
--dir latest - -
--run latest - -
--report classes - required
--build classes - -

Refuses (12 messages, as the code writes them):

  • line 236: the Unreal record names no dt - the frames' step is never assumed
  • line 297: REFUSED: --step %s is not a positive time
  • line 302: REFUSED: time(s) %s are not on the %.6f s grid - no Unreal frame meets them
  • line 316: REFUSED: no IR keys selected from %s
  • line 321: REFUSED: %s exists - nothing is replaced
  • line 327: REFUSED: %s
  • line 597: %s %s matches %s - the classes overlap
  • line 612: REFUSED: no --build and the project names no U2UE_EFFECTS_DIR to find u1e-build-newest.json in
  • line 638: REFUSED: the report's Unreal record names no dt in its header - the class tests have no step to judge at
  • line 667: REFUSED: no --run and the project names no conform.standing_run - which run is the score is the project's choice
  • line 674: REFUSED: %s unreadable: %s
  • line 684: REFUSED: no stamped conformance report%s under %s - run 'conform diff --report'

Exits: 0, 1, 2. Its docstring: conform.standing_run unless --run): "CONFORM OK n of m (x %)" - STALE (exit 1) when another judge made it

Verified by: py -m u2ue.verbs.conform --selftest - last run passes (exit 0) (u2ue/survey/pt1_selftests.json).

Exercised by: UC-08 step 1, UC-08 step 4, UC-08 step 5, UC-08 step 6.

FR-JUDGE judge

Requirement (the registry row, u2ue/verbs/__init__.py): every judge the trials run, the trials that run it, and whether its plant can refuse (its --selftest, or a trial's declared plant).

Implemented by u2ue/verbs/judge.py (21 lines; public: run). Needs a project: yes. Its usage text is in Chapter 20.

Inputs: read by hand from its arguments - --mode, --prove, --selftest.

Refuses: no refusal message of its own; it stops with the exit of the tool it runs.

Exits: the exit of the tool it runs. Its docstring: py -m u2ue --project judge --prove runs each judge's --selftest; exit 1 when one fails or a judge has no plant

Verified by: ABSENT - the selftest registry runs no selftest of this verb.

Exercised by: UC-13 step 4.

FR-EXTRACT extract

Requirement (the registry row, u2ue/verbs/__init__.py): Unity prefabs -> the engine-neutral IR (no editor runs).

Implemented by u2ue/verbs/extract.py (204 lines; public: check, run). Needs a project: yes. Its usage text is in Chapter 20.

Inputs:

option for what it is notes
--steps all - -
--out all - -
--resolve all - -

Refuses (1 messages, as the code writes them):

  • line 109: REFUSED %s: %s

Exits: 0, 1, 2. Its docstring: Checked after the ir step, exit 1 on any:

Verified by: ABSENT - the selftest registry runs no selftest of this verb.

Exercised by: UC-02 step 5, UC-18 step 5, UC-20 step 2.

FR-CHECK check

Requirement (the registry row, u2ue/verbs/__init__.py): the toolkit's selftests, the project's field gates, the measured rules' Unity versions.

Implemented by u2ue/verbs/check.py (125 lines; public: facts, gates, model, run, selftests). Needs a project: yes. Its usage text is in Chapter 20.

Inputs:

option for what it is notes
--only all - one of ('selftests', 'gates', 'facts', 'model')
--tool all - nargs '*'

Refuses: no refusal message of its own; it stops with the exit of the tool it runs.

Exits: the exit of the tool it runs. Its docstring: here), then the project file's own rows (selftests: the gates written against that one game); each must exit 0; in a Its docstring: Exit 1 when any one fails. Nothing launches Unreal or Unity; below normal priority.

Verified by: ABSENT - the selftest registry runs no selftest of this verb.

Exercised by: UC-05 step 3, UC-15 step 6, UC-16 step 5, UC-16 step 6, UC-16 step 11, UC-18 step 6, UC-20 step 3, UC-21 step 1.

FR-BUILD build

Requirement (the registry row, u2ue/verbs/__init__.py): IR -> Niagara systems under the project's content root (Unreal, headless).

Implemented by u2ue/verbs/build.py (118 lines; public: run). Needs a project: yes. Its usage text is in Chapter 20.

Inputs:

option for what it is notes
--keys all - -
--tag all - default 'u2ue'
--batch all - default 12
--no-resave all - a flag
--dry all - a flag

Refuses (2 messages, as the code writes them):

  • line 59: u2ue build: REFUSED - %s
  • line 63: u2ue build: REFUSED - %s

Exits: 0, 1, 2.

Verified by: ABSENT - the selftest registry runs no selftest of this verb.

Exercised by: UC-18 step 7, UC-20 step 4.

FR-READ read

Requirement (the registry row, u2ue/verbs/__init__.py): the built systems read back frame by frame (Unreal, headless).

Implemented by u2ue/verbs/read.py (70 lines; public: run). Needs a project: yes. Its usage text is in Chapter 20.

Inputs:

option for what it is notes
--tag all - default 'u2ue'
--frames all - default 90
--dry all - a flag

Refuses (2 messages, as the code writes them):

  • line 41: u2ue read: REFUSED - %s
  • line 45: u2ue read: REFUSED - %s

Exits: 0, 1, 2. Its docstring: system that captured no frame, or fewer than asked, is named and the verb exits 1. Refuses while the Unreal host is busy.

Verified by: ABSENT - the selftest registry runs no selftest of this verb.

Exercised by: UC-18 step 7, UC-20 step 5.

FR-PHOTO photo

Requirement (the registry row, u2ue/verbs/__init__.py): the built systems photographed, paired with Unity's frames (Unreal, headless).

Implemented by u2ue/verbs/photo.py (231 lines; public: run, selftest, unity_list). Needs a project: yes. Its usage text is in Chapter 20.

Inputs:

option for what it is notes
--tag all - default 'u2ue'
--times all - default '0.1,0.3,0.6,1.0'
--dry all - a flag
--unity-list all - as FILE

Refuses (4 messages, as the code writes them):

  • line 40: u2ue photo: REFUSED %s
  • line 66: u2ue photo: REFUSED - %s
  • line 70: u2ue photo: REFUSED - %s
  • line 75: u2ue photo: REFUSED - the project names no work.effects (U2UE_EFFECTS_DIR), where the photo tool writes its result

Exits: 0, 1, 2.

Verified by: py -m u2ue.verbs.photo --selftest - last run passes (exit 0) (u2ue/survey/pt1_selftests.json).

Exercised by: UC-18 step 7, UC-20 step 6.

FR-REPORT report

Requirement (the registry row, u2ue/verbs/__init__.py): the acceptance page from the project's records.

Implemented by u2ue/verbs/report.py (50 lines; public: run). Needs a project: yes. Its usage text is in Chapter 20.

Inputs:

option for what it is notes
--out all - -

Refuses: no refusal message of its own; it stops with the exit of the tool it runs.

Exits: 0, 1, 2.

Verified by: ABSENT - the selftest registry runs no selftest of this verb.

Exercised by: UC-11 step 5, UC-18 step 8, UC-20 step 7.

FR-METRICS metrics

Requirement (the registry row, u2ue/verbs/__init__.py): the port's numbers, each from a record, with its definition.

Implemented by u2ue/verbs/metrics.py (193 lines; public: run). Needs a project: yes. Its usage text is in Chapter 20.

Inputs:

option for what it is notes
--json all - -

Refuses: no refusal message of its own; it stops with the exit of the tool it runs.

Exits: 0, 1.

Verified by: ABSENT - the selftest registry runs no selftest of this verb.

Exercised by: UC-11 step 5, UC-18 step 8, UC-20 step 8.

FR-TEMPO tempo

Requirement (the registry row, u2ue/verbs/__init__.py): each verified route's first code -> verified flip, read off git.

Implemented by u2ue/verbs/tempo.py (221 lines; public: measure, run, selftest). Needs a project: yes. Its usage text is in Chapter 20.

Inputs:

option for what it is notes
--json all - -
--since all only routes flipped on or after this date (YYYY-MM-DD) -

Refuses (2 messages, as the code writes them):

  • line 35: u2ue tempo: %s is not in a git repository (%s)
  • line 49: u2ue tempo: git log failed for %s: %s

Exits: 0, 2.

Verified by: py -m u2ue.verbs.tempo --selftest - last run passes (exit 0) (u2ue/survey/pt1_selftests.json).

Exercised by: UC-20 step 9.

FR-CYCLE cycle

Requirement (the registry row, u2ue/verbs/__init__.py): every pillar of the product checked: PASS / FAIL / HELD by a named decision / ABSENT (no check yet).

Implemented by u2ue/verbs/cycle.py (308 lines; public: CommitGate, baseline_record, cycle, run, selftest, staged_files). Needs a project: yes. Its usage text is in Chapter 20.

Inputs:

option for what it is notes
--pillar all - nargs '*'
--dry all - a flag
--commit all the commit gate: the commit-marked checks, when a toolkit file is staged a flag

Refuses (2 messages, as the code writes them):

  • line 123: git diff --cached failed: %s
  • line 141: u2ue cycle --commit: REFUSED - no full cycle has run (%s): its trends have no baseline to hold to. Run 'py -m u2ue --project %s cycle' once.

Exits: 0, 1. Its docstring: cycle reads it for every Trend (a number that must not move the wrong way). Exit 1 when any pillar is FAIL - red stops the cycle.

Verified by: py -m u2ue.verbs.cycle --selftest - last run passes (exit 0) (u2ue/survey/pt1_selftests.json).

Exercised by: UC-07 step 1, UC-07 step 2, UC-07 step 3, UC-07 step 4, UC-07 step 5, UC-07 step 6, UC-07 step 7, UC-07 step 8, UC-07 step 9, UC-07 step 10, UC-07 step 11, UC-11 step 6.

FR-TOOL tool

Requirement (the registry row, u2ue/verbs/__init__.py): one tool of the toolkit run by hand, found by its file name, with the project's variables (u2ue/env.py).

Implemented by u2ue/verbs/tool.py (87 lines; public: command, find, run, selftest). Needs a project: yes. Its usage text is in Chapter 20.

Inputs: read by hand from its arguments - --selftest.

Refuses (1 messages, as the code writes them):

  • line 40: %s is neither a .py nor a .ps1 tool

Exits: 2. Its docstring: folder, their output streamed through and their exit code returned. A tool that starts Unreal keeps its own guards (one Unreal at a

Verified by: py -c "import sys; from u2ue.verbs import tool; sys.exit(tool.selftest())" - last run passes (exit 0) (u2ue/survey/pt1_selftests.json).

Exercised by: UC-09 step 5.

FR-RELEASE release

Requirement (the registry row, u2ue/verbs/__init__.py): the package as a repo: assembled from the toolkit's own trees by one manifest, secrets refused, public readiness counted.

Implemented by u2ue/verbs/release.py (958 lines; public: run, selftest). Needs a project: no. Its usage text is in Chapter 20.

Inputs:

option for what it is notes
--to all the repo folder: empty, or a checkout an earlier release wrote -
--dry all say what would be written and deleted; write nothing a flag
--check all exit 1 when the folder differs from what the manifest writes a flag
--store all the Unity half as an Asset Store UPM product (StorePackage) a flag
--prove all assemble the release into a fresh folder (--to, else a temp one), make it a git checkout of itself and run PROJECT's check --only selftests INSIDE it - name a game other than the reference port (ReleaseProof) as PROJECT
--namespace all --store: the publisher namespace the UPM enrolment reserved, exactly as Unity writes it (com.example); the package is .u2ue, and --to must be a folder of that name -
--compile all --store: compile the package alone against the project's editor (Unity's own assemblies only) a flag
--classic all --store: the classic layout (an Asset Store .unitypackage): one folder u2ue under the Unity project's Assets folder that --to names, no package.json, no namespace a flag

Refuses (9 messages, as the code writes them):

  • line 61: REFUSED: --to <DIR> names the repo folder
  • line 73: REFUSED: %s
  • line 109: REFUSED: %s
  • line 126: REFUSED: %s
  • line 137: REFUSED: --compile compiles against a Unity project's editor: name it with --project (its unity.root)
  • line 142: REFUSED: %s
  • line 167: REFUSED: writing the package needs --compile - its package.json names the Unity version it was compiled against (PackageCompile), never one typed in
  • line 171: REFUSED: %d rule(s) broken - nothing written
  • line 176: REFUSED: %s

Exits: 0, 1, 2. Its docstring: py -m u2ue release --check --to

exit 1 when DIR differs from what the manifest would write (a stale release) Its docstring: Exit 0 = assembled (or current); 1 = --check found a difference; 2 = refused (a secret, a folder that is not a release, no --to).

Verified by: py -m u2ue.verbs.release --selftest - last run passes (exit 0) (u2ue/survey/pt1_selftests.json).

Exercised by: UC-19 step 1, UC-19 step 2, UC-19 step 3.

FR-BLUEPRINT blueprint

Requirement (the registry row, u2ue/verbs/__init__.py): the Blueprint view (a quarantined experiment): a Blueprint's text to code, every node traced to its use case step and requirement, a 3D city; doctor and install its prerequisites; its tests on real data.

Implemented by u2ue/verbs/blueprint.py (301 lines; public: Prerequisite, build, doctor, gates, install, prerequisites, run, selftest). Needs a project: no. Its usage text is in Chapter 20.

Inputs: read by hand from its arguments - --allow-missing, --offline, --quick, --selftest, --unity, --yes.

Refuses (2 messages, as the code writes them):

  • line 268: u2ue blueprint test: REFUSED - no option %s; it reads %s
  • line 282: u2ue blueprint package: REFUSED - after the package's path it reads only --unity <Unity project> (--project is the facade's own)

Exits: 0, 2.

Verified by: py -m u2ue.verbs.blueprint --selftest - last run registered, never run (u2ue/survey/pt1_selftests.json).

Exercised by: no use-case step runs it as its proof.

20. Command reference

Generated by u2ue/manual/build.py from the facade's verb registry (u2ue/verbs/__init__.py) and each verb's own docstring - edit the code, not this page.

Who this is for: the toolkit developer and the reviewer - each verb's full usage text, exactly as the code prints it; read it when Chapter 19 or a procedure names a verb's option.

Every command runs from the toolkit's root (the folder that holds u2ue/):

py -m u2ue                                   # list every verb
py -m u2ue find <words>                      # search everything the toolkit holds (no project)
py -m u2ue --project <name|file.json> <verb> [options]
verb needs a project what it does
find no search everything the toolkit holds: verbs, adapters, tools, docs, measured rules, converter stages, routes
estimate no what porting a Unity project will cost in model tokens: its code and assets read, times rates measured on a real port, with the cache split, the list cost and the confidence
port yes the whole port as one command: every stage in order, each read from its own records; runs what a verb can, stops with one question where a person, the AI or an editor is needed
info yes every path the project names, OPENED; its adapter
inventory yes the game's own C#, type by type: Unity API by family, pure rules, the frame order (no editor runs)
uml yes the game's class model off its own code roots (and its model once scaffolded): extract, mermaid, where, ask
scaffold yes the engine-free model a game's rules move into: created, declared in the project file, built and gated
slice yes every check one slice of a logic refactor must pass before it lands: builds, tests against a recorded baseline, the model gates, Unity compiled headlessly (optionally from an overlay), parity
cite yes every File.cs:N breadcrumb in the model's comments held to the code it names: a quoted one HOLDS, MOVED (to the line it is on now) or BROKEN; one with no quote counted
mutate yes would any test notice if a rule changed: each mutation a file lists applied to a fresh copy of what the project file declares, the tests run there - CAUGHT, SURVIVED, COMPILE-BREAK, NO-RESULT or ANCHOR-MISS, ending MUTANTS NOT CAUGHT n of m; the project's own files never written
req yes every // REQ: citation in the game's code resolved in the requirement documents its project file names: HOLDS (a line that says something, an id a line starts with, a section the document defines, a folder's entry), TAGGED (one of its tags: no designer requirement, declared) or UNRESOLVED (to the designer)
logic yes where this project's logic port stands: each u2ue-logic skill step judged by its own DONE WHEN, read from its records
data yes a component's or ScriptableObject's serialized values off a scene / prefab / asset, overrides applied (no editor runs)
shear yes the scene nodes Unreal cannot place as Unity does (a sheared transform chain), with the error in cm
scene yes a Unity scene as an Unreal level: export (in a window), import, readback, and the fidelity gate against its own baseline
parity yes the game's rules on every runtime they run on, compared by float bits with a characterised allowance
digest yes the game's rule cases answered with no engine: on CoreCLR (Headless) and on that Unity's own Mono (UnityMono)
host yes the game's OWN Unreal project, made as a customer makes one: create, install, compile, generate, wire, publish, run
ui yes a Unity UI screen converted to a folder Unreal reads; the generic uGUI / TextMeshPro library's tests
window yes ONE Unity measurement window from a data file: idle-gated, owner-stoppable, nothing replaced, md5-held
trial yes a route's TRIAL in Unreal from a data file: build, resave, read, judge, photos; one Unreal at a time, stoppable
conform yes data-first conformance over all keys: Unity's particle state (one generic probe) against Niagara's readback, paired by file id
judge yes every judge the trials run, the trials that run it, and whether its plant can refuse (its --selftest, or a trial's declared plant)
extract yes Unity prefabs -> the engine-neutral IR (no editor runs)
check yes the toolkit's selftests, the project's field gates, the measured rules' Unity versions
build yes IR -> Niagara systems under the project's content root (Unreal, headless)
read yes the built systems read back frame by frame (Unreal, headless)
photo yes the built systems photographed, paired with Unity's frames (Unreal, headless)
report yes the acceptance page from the project's records
metrics yes the port's numbers, each from a record, with its definition
tempo yes each verified route's first code -> verified flip, read off git
cycle yes every pillar of the product checked: PASS / FAIL / HELD by a named decision / ABSENT (no check yet)
tool yes one tool of the toolkit run by hand, found by its file name, with the project's variables (u2ue/env.py)
release no the package as a repo: assembled from the toolkit's own trees by one manifest, secrets refused, public readiness counted
blueprint no the Blueprint view (a quarantined experiment): a Blueprint's text to code, every node traced to its use case step and requirement, a 3D city; doctor and install its prerequisites; its tests on real data

find

search everything the toolkit holds: verbs, adapters, tools, docs, measured rules, converter stages, routes.

u2ue find - search everything the toolkit holds (u2ue/catalog.py): verbs, adapters, tools, doc sections, measured Unity rules,
converter functions and stages, verified routes. No project needed.

    py -m u2ue find <words ...> [--kind concept,verb,adapter,tool,doc,rule,converter,route] [--top N] [--selftest]

Every word must appear (in the name, the summary or the body); the results come grouped by kind, best first, each with WHERE it
lives (file:line) - the place to open next.

estimate

what porting a Unity project will cost in model tokens: its code and assets read, times rates measured on a real port, with the cache split, the list cost and the confidence.

u2ue estimate - what porting a Unity project will cost in model tokens on Opus 5.5, from MEASURED rates (u2ue/estimate.py).

    py -m u2ue estimate --unity <Unity project> [--roots A,B] [--model M] [--json OUT]    point it at any Unity project
    py -m u2ue --project <name> estimate [--json OUT]                                       the project's unity.root and code.roots
    py -m u2ue.verbs.estimate --selftest

What it prints, every number with where it came from:
  the project   READ off its files (Census): the C# code lines per top folder, split COUPLED (uses a Unity API family, a lifecycle
                method or a Unity base) and PURE; Editor folders apart (not ported); scenes in the build settings; particle
                prefabs; prefabs and scenes with a Canvas. With no --roots every folder under Assets is counted and listed, so the
                game's own folders can be named (vendor packages live in Assets too) - the logic line is then an upper bound
  the estimate  per stage: the logic (AI - lines x the measured tokens per line of the reference port's extraction, all-in),
                the conductor's stops (AI - one turn each at the measured tokens per call), everything a verb does (AUTOMATIC -
                no model tokens); the total in the five token kinds, the share the prompt cache served, the list cost at the
                model's READ prices (u2ue/basis/prices.json), the same calls' cost with no caching, a bootstrap band
  the saving    what the reference port's agents spent per unit on the stages the verbs now do (scenes), where measured
  confidence    HIGH / MEDIUM / LOW per stage and why (samples, the model it was measured on, how far outside the basis)

The basis (u2ue/basis/tokens.json) is written by u2ue/survey/token_basis.py from a project's own records. Exit 0 = estimated;
2 = refused (no Unity project, no price for the model, a basis with a rate missing).

port

the whole port as one command: every stage in order, each read from its own records; runs what a verb can, stops with one question where a person, the AI or an editor is needed.

u2ue port - the whole port as ONE command (u2ue/port.py: PortPlan, Stage, PortRun).

    py -m u2ue --project <name> port                       every stage's state, read from its records, and the next action
    py -m u2ue --project <name> port --run                 also run the AUTOMATIC stages that are TODO, in order
    py -m u2ue --project <name> port --run --with-unreal   ... the ones that launch a headless Unreal too (one at a time)
    py -m u2ue.verbs.port --selftest

Without --run nothing is started but the read-only checks (info, host status, scene check, check --only gates, parity). With
--run each AUTOMATIC stage that reads TODO runs through its own verb and is read again; a RED stage holds back only the stages that wait on it. An
EDITOR stage never runs here (a Unity editor is the owner's: its window is named, and `u2ue window` runs one only while the editor
is idle); an AI stage hands over to the skill (u2ue-logic, kept going by u2ue-long-run); an OWNER stage asks its question.
Running it again resumes: every state is read from the records each time.

Exit 0 = nothing left (every stage DONE, or ABSENT / UNCHECKED and said); 1 = something is left, the next action printed;
2 = refused. --run writes <work.records>/port/port-<stamp>.json and port-latest.json.

info

every path the project names, OPENED; its adapter.

u2ue info - every path the project names, OPENED (exit 1 when an INPUT is missing), its adapter and its key source.

inventory

the game's own C#, type by type: Unity API by family, pure rules, the frame order (no editor runs).

u2ue inventory - what a Unity game's own C# asks of the engine, type by type.

    py -m u2ue --project <name> inventory [--survey] [--roots Assets/A,Assets/B] [--out DIR]
    py -m u2ue --project <name> inventory --mvc [--out DIR]     the MVC census (u2ue-mvc step 1): every MonoBehaviour's instance
             state member by member - RUNTIME / AUTHORED / REFERENCE / STATIC / UNPLACED - and the model's members of the same name

--survey     every top folder under Assets with its count of .cs files (Editor folders apart) - read this first, then name the
             game's own folders as code.roots in the project file (never guessed: vendor packages live in Assets too)
default      reads every .cs under code.roots (the project file's, or --roots) and writes DIR/inventory.json + DIR/inventory.md:
  per type   its kind (MonoBehaviour / ScriptableObject - through the project's own base classes, transitively - or plain, or a base
             the scanned code does not declare, named), its Unity lifecycle methods, and every Unity API it uses by FAMILY, each
             family pointing at the manual's section that says how it ports
  pure rules the types that use no Unity API at all - what moves into an engine-free model first
  frame      every MonoBehaviour's script execution order (its .cs.meta executionOrder) and the lifecycle methods it has, in
  order      Unity's frame order - the table a frame driver is written from (U2ue.Runtime's UnityFrame takes it)
How it reads: comments and strings are blanked first (a name in a comment or a string is not a use); a brace stack tells which
type a line belongs to (nested types apart); a token counts on word boundaries. It is a LEXICAL reader: a call through an alias,
reflection or a generic helper is not seen - the report says so, and a miss is UNKNOWN, never "does not use".

uml

the game's class model off its own code roots (and its model once scaffolded): extract, mermaid, where, ask.

u2ue uml - the game's class model, off ITS OWN code roots (logic-port skill step 2: "draw the class model of one slice before moving
anything").

    py -m u2ue --project <name> uml extract                           the class model of the game's code (+ its model, once scaffolded)
    py -m u2ue --project <name> uml mermaid --focus TypeA TypeB        a class diagram of a slice, every member a real one
    py -m u2ue --project <name> uml where|ask|callers|tests <Name>     lookups over the same model
    py -m u2ue --project <name> uml <any other uml.py subcommand>

This wraps .opus-tools/uml.py (the facade never rewrites a tool) with the project's roots and its own index folder, so one game's
model never lands on another game's index:
  roots   every code.roots folder under unity.root, then every model.scan folder under model.root once the project declares a model
  index   <work.inventory>/uml (uml.py --cache)
  doc     check / graph / triples read the game's use-case model, code.usecases under unity.root (uml.py --doc)
A project with no code.roots is refused: name them first (`u2ue inventory --survey`), never guessed. So is a check with no
code.usecases: uml.py's own default document is the reference game's, and a second game's check would hold the reference game's
use cases to its code (TASKS F6, found 10-17). Write the game's own first (the usecase-map skill).

scaffold

the engine-free model a game's rules move into: created, declared in the project file, built and gated.

u2ue scaffold - the engine-free model a game's rules move into, created, declared and gated in one command (logic-port skill step 4;
the method's recipe step 1: "Write your Core. An engine-free project with NO references at all").

    py -m u2ue --project <name> scaffold --name <Model> --dir <DIR> [--dry]
    py -m u2ue.verbs.scaffold --selftest

Writes, under DIR (refused if any of it exists - a scaffold never overwrites):
  <Model>.Core/<Model>.Core.csproj              netstandard2.1 (Unity 2021+ loads it) + net8.0 (tests, hosts); it references ONLY
                                                U2ue.Runtime (the toolkit's engine-free frame / clock / coroutine / platform library)
  <Model>.Core/README.md                        what belongs in it, in four lines, and the gate that holds it
  <Model>.Core.Tests/<Model>.Core.Tests.csproj  NUnit, headless (`dotnet test`) - where each ported rule's test goes
and adds the project file's "model" block (root, layers, scan, hosting) - the block `u2ue check --only model` reads - then builds
both projects and runs that check. Exit 0 = the model exists, compiles, and its gates pass on it; 1 = a build or a gate failed;
2 = refused (a model already declared, a path that exists, no --name / --dir).

The bones, in one analogy: the Core is the game's RULEBOOK - it says what happens, never how it looks; the engines are the TABLES
the game is played on. layer_gate keeps any engine out of the rulebook; host_gate keeps platform chores (logging, files, random
numbers) on the one shared shelf, U2ue.Runtime's Platform interfaces, instead of re-declared on every rule's host.

slice

every check one slice of a logic refactor must pass before it lands: builds, tests against a recorded baseline, the model gates, Unity compiled headlessly (optionally from an overlay), parity.

u2ue slice - every check one slice of a logic refactor must pass before it lands (u2ue/slice.py SliceGate; the u2ue-mvc skill).

    py -m u2ue --project <name> slice                         build, tests against the baseline, model gates, Unity compile, parity
    py -m u2ue --project <name> slice --overlay <DIR>         the same, with Unity's scripts compiled from a scratch overlay
                                                              (DIR/Assets/...) instead of the live project
    py -m u2ue --project <name> slice --baseline --because <why>   record the failing test names BEFORE a slice starts
    py -m u2ue --project <name> slice cut --overlay <DIR> <Assets/...> [...]   copy live files into an overlay, recording each hash
    py -m u2ue --project <name> slice cut --overlay <DIR> --on <EARLIER> [--on ...] <Assets/...>
                                                              the same ON slices that have not landed yet: their files first,
                                                              with the hashes the live files will have once they land
    py -m u2ue --project <name> slice rebase --overlay <DIR> [--overlay <DIR> ...]   a slice cut --on earlier ones takes their
                                                              changes since the cut (files it left as it found them; a file both
                                                              changed is refused), in landing order; then gate it again
    py -m u2ue --project <name> slice land --seed <N> --overlay <DIR> [--compare before|null] [--ignore-kinds K,.. --because <why>]
                                          [--ignore-rows "K:FIELD=V;K:FIELD!=V" --because <why>] [--battle ai|clicks|clicks-undo|clicks-undo-midwalk]
                                          [--ignore-fields "K:FIELD;.." --because <why>]
                                          [--handed-over "<the owner's words>"]
                                          [--overlay <DIR> ...] [--mode <title mode>]
                                                              write the overlay into the live project in the owner's absence,
                                                              compile, and PLAY a seeded battle (before and after, or twice);
                                                              several overlays land in order, each after the one before PASSED;
                                                              the options after an --overlay are its own. --ignore-kinds: event
                                                              kinds a slice changes BY DECISION, left out of the comparison of the
                                                              row-named events (the reason is required and recorded);
                                                              --ignore-rows: only the rows of a kind a rule names, on a column of
                                                              events.rows (e.g. "6:side!=0", the flow's cast summary); the v3
                                                              extras aligned with a row are left out with it. --ignore-fields:
                                                              ONE field of a kind's v3 extras (e.g. "2:path", a move's walk once
                                                              a slice reports it), the row and its other fields still compared.
                                                              --battle clicks:
                                                              the player's turns are played through the player's own click path
                                                              (deploy_record_run --clicks) for a slice that changes it;
                                                              clicks-undo, the same with the first walk undone and made
                                                              again (--undo-first-move), for a slice that moves Cancel;
                                                              clicks-undo-midwalk, the first walk of two squares or more undone
                                                              WHILE IT PLAYS (--undo-mid-walk), Cancel's PlayerMovement branch;
                                                              ai, the default, is AutoBattle on both sides. An overlay's
                                                              .slice-steps.json declares editor steps (SliceStep): a menu run
                                                              after the slice compiles, before the proofs and the battle on the
                                                              new code, and the files it writes - backed up, never another
                                                              writer's, put back with the slice unless it PASSES
    py -m u2ue.verbs.slice --selftest                         every verdict proven on planted input, nothing built, no editor

Exit 0 = every check passed (the slice may land) / the landing PASSED; 1 = a check failed (each named, with its first error) / the
landing FAILED or STOPPED (restored either way); 2 = refused (no model, no baseline, a reasonless baseline, a landing whose overlay
moved, whose gate did not pass, whose editor is busy, whose earlier slice has not landed, or whose Unity scripts do not compile
headlessly against the plugins that will be live). Each run writes <work.records>/slice/slice-latest.json; a landing writes
<work.records>/slice/landing-<stamp>/ (its backups, both battles, landing.json). The gate alone never proves the Unity game PLAYS
the same; `land` is the step that does, and it runs only while the owner is away (600 s of quiet, a presence watch).

cite

every File.cs:N breadcrumb in the model's comments held to the code it names: a quoted one HOLDS, MOVED (to the line it is on now) or BROKEN; one with no quote counted.

u2ue cite - every `File.cs:N` breadcrumb in the model's comments, held to the code it names (u2ue/citation.py: CitationCheck).

    py -m u2ue --project <name> cite             the citations in the project's model.scan folders, resolved against its model and
                                                 host folders: HOLDS, MOVED (with the lines the quote is on now), BROKEN (the quote
                                                 is gone), UNQUOTED (a line number alone, counted), UNRESOLVED (no such file, or two).
                                                 A QUOTE-ONLY citation (`File.cs `quote``, no line - CITE-1b) HOLDS wherever its quote
                                                 is and is BROKEN when it is gone: the form that survives an edit to the file
    py -m u2ue --project <name> cite --list MOVED|BROKEN|UNRESOLVED|UNQUOTED   every citation with that verdict
    py -m u2ue.verbs.cite --selftest             each verdict proven on planted files

Exit 0 = no quoted citation is BROKEN; 1 = one is (each named); 2 = refused (the project names no model). A MOVED citation is
reported, not failed: its quote still says where the code is. Nothing is rewritten - a citation's owner moves it.

mutate

would any test notice if a rule changed: each mutation a file lists applied to a fresh copy of what the project file declares, the tests run there - CAUGHT, SURVIVED, COMPILE-BREAK, NO-RESULT or ANCHOR-MISS, ending MUTANTS NOT CAUGHT n of m; the project's own files never written.

u2ue mutate - would any test notice if a rule changed? Each mutation a file lists is applied to a FRESH copy of what the project
file's `mutation` block declares, the tests run there, and the copy put back (u2ue/mutation.py: MutationRun) - so no open editor and
no other build ever sees a mutant, and the project's own files are never written.

    py -m u2ue --project <name> mutate MUTATIONS.json              every row: CAUGHT, SURVIVED, COMPILE-BREAK, NO-RESULT, ANCHOR-MISS
    py -m u2ue --project <name> mutate MUTATIONS.json --only LABEL one row, by its label
    py -m u2ue --project <name> mutate MUTATIONS.json --keep       leave the copy to look at (its folder is printed)

A row is {"file", "label", "old", "new", "claim"} and an optional "filter" (dotnet test --filter; the file's own "filter" is the
default). A mutation must change BEHAVIOUR and still compile: a rename only breaks the build, which every test catches for free.

Exit 0 = every mutation CAUGHT and the untouched copy green again after; 1 = `MUTANTS NOT CAUGHT n of m` with n above 0 - SURVIVED
(write the test that notices), COMPILE-BREAK (not a mutation), NO-RESULT, ANCHOR-MISS (the rule moved on: rewrite the row) - or
the copy red after the run; 2 = refused (no mutation block, a bad row, a copy entry that matches nothing, a build step that can
write outside the copy, a red baseline).

req

every // REQ: citation in the game's code resolved in the requirement documents its project file names: HOLDS (a line that says something, an id a line starts with, a section the document defines, a folder's entry), TAGGED (one of its tags: no designer requirement, declared) or UNRESOLVED (to the designer).

u2ue req - every `// REQ:` citation in the game's code, resolved in the requirement documents the project file names
(u2ue/requirements.py: RequirementCheck): HOLDS (read in a source: a line that says something, an id a line starts with, a section
the document defines, an entry of a folder), TAGGED (one of the project's tags: no designer requirement behind it, and why) or
UNRESOLVED (it goes to the designer).

    py -m u2ue --project <name> req [PATH ...]      the paths given, or the project's requirements.roots
    py -m u2ue --project <name> req --unresolved    only the citations that do not hold

UNRESOLVED citations that one line offset explains (every cited line's neighbour at +N says something) are counted together by
source and offset: on the reference port 1073 of them were one offset of +1 in one file - one fix, not a thousand. Nothing is
rewritten: a citation's owner moves it.

Exit 0 = every citation holds or is tagged; 1 = one or more UNRESOLVED, or no citation at all under the paths (a check that read
nothing proves nothing); 2 = refused (no requirement sources in the project file, no paths, a source or a path missing).

logic

where this project's logic port stands: each u2ue-logic skill step judged by its own DONE WHEN, read from its records.

u2ue logic - where this project's logic port stands: each step of the u2ue-logic skill judged by its own DONE WHEN, read from the
project's records now (u2ue/logic.py: LogicPort). An AI porter, or a person, starts a session here instead of re-deriving the state.

    py -m u2ue --project <name> logic             every step: DONE / NOT YET / JUDGED (a reviewer's call) / NOT RUN (a test run
                                                  it names) - and the step to take next
    py -m u2ue.verbs.logic --selftest             a skill step whose title moved is refused; a project with no model reads NOT YET
                                                  from Step 4; the real skill's steps all have a check
Nothing is written and nothing is built; the checks it runs are the toolkit's own (info, check --only model, parity).

data

a component's or ScriptableObject's serialized values off a scene / prefab / asset, overrides applied (no editor runs).

u2ue data - a component's serialized values, or a ScriptableObject's, READ off the Unity file.

    py -m u2ue --project <name> data --from <Assets/...unity|.prefab|.asset> (--script <ClassName> | --class <id or Unity type>)
                                     [--out FILE.json] [--tsv FILE.tsv] [--no-expand]

What the inspector shows is what the scene or prefab STORES - "Unity serialization beats the C# initializer" - so a port reads it
there and never retypes it. This finds every component that matches:
  --script  a MonoBehaviour whose m_Script is the .cs file named <ClassName>.cs (its guid from the project's guid index - never a
            line number; a file Unity has re-saved moves its lines)
  --class   a built-in component by class id (20 Camera, 4 Transform, 108 Light, ...) or its YAML type name (Camera, Light, ...)
in the file with its NESTED prefab instances expanded and their modifications applied (the IR reader's own u1e_nested: a value an
override changed is the override's), and writes per component: its GameObject's path from the root, its fileID, and every field as
the file stores it - a reference {fileID, guid} carries the asset path it names. --tsv also writes one `<dotted path>   <value>` row
per leaf (lists as path[i]), a form two readers' outputs can be diffed in. A ScriptableObject .asset is one MonoBehaviour: --script
names its class. Bookkeeping fields (m_ObjectHideFlags, m_CorrespondingSourceObject, m_PrefabInstance, m_PrefabAsset,
m_EditorHideFlags, m_EditorClassIdentifier) are left out, every one by that list.

shear

the scene nodes Unreal cannot place as Unity does (a sheared transform chain), with the error in cm.

u2ue shear - the scene nodes Unreal cannot place as Unity does (BASICS section 9).

    py -m u2ue --project <name> shear (--gltf FILE.gltf | --from Assets/....unity|.prefab [--no-expand]) [--json OUT] [--eps 1e-6]

A Unity Transform composes as a MATRIX, so a rotated child under a non-uniformly scaled parent is SHEARED; an Unreal component holds
translation + rotation + scale and drops the shear at every level. For every node this composes its chain BOTH ways (u2ue.transform:
compose_matrix and compose_trs) and reports the sheared ones - the axes' worst |cosine| (nonOrthogonality) and how far the corners
of a unit cube at the node land apart (unitCornerCm) - and whether the node DRAWS (a glTF mesh; in YAML an active MeshRenderer or
SkinnedMeshRenderer on it). A sheared node that draws nothing still moves its children: the list says which. Whether the error is
accepted, baked or fixed in the Unity scene is the porter's call, made WITH the number, and pinned by a gate once made.
--gltf     a scene exported by the scene pipeline (glTFast): its nodes as exported (inactive subtrees left out by the exporter)
--from     the scene or prefab YAML itself, nested prefab instances expanded with their overrides (u1e_nested); no export needed

scene

a Unity scene as an Unreal level: export (in a window), import, readback, and the fidelity gate against its own baseline.

u2ue scene - a Unity scene as an Unreal level, and the proof it still looks like the Unity scene.

    py -m u2ue --project <name> scene export [--out DIR]
    py -m u2ue --project <name> scene import
    py -m u2ue --project <name> scene readback
    py -m u2ue --project <name> scene check [--no-parity] [--json FILE]
    py -m u2ue --project <name> scene --dry
    py -m u2ue --project <name> scene import|readback|check --dir DIR --content /Game/...   (a trial: its own folder and root)
    py -m u2ue.verbs.scene --selftest

  export    the scene as glTF (glTFast: meshes, materials and textures one to one, inactive subtrees listed, the terrain baked from
            its TerrainData). It runs in the game's own Unity Editor, so this verb never touches an editor: it prints the trigger a
            window drops (.RUN_SCENE_EXPORT, whose one line is the output folder) and refuses by name. The exporter is the reference
            port's Editor script; for any other game it is planned to ship as the package's Editor assembly.
  import    the exported glTF into a NEW Unreal level through Interchange's own scene pipeline - the engine's default glTF stack,
            nothing hand-placed (Unreal, headless, from native PowerShell, one Unreal at a time).
  readback  the saved level read back headless: every actor and attach chain, every material slot and its root material, every
            material instance's parameters, every texture asset in the scene's folder, the lights (Unreal, headless).
  check     the fidelity gate (scene_fidelity_gate.py): hierarchy, materials, textures, lighting and placement against Unity's own
            files and the scene's OWN measured baseline (<scene dir>/fidelity-baseline.json); exit 1 the moment one moves, 2 when an
            input or the baseline is missing (no editor runs).
  --dry     the scene's paths, opened, and the host's state.

The project names its scene - "scene": {"unity": "Assets/<Scene>.unity", "name": "<Name>", "dir": "<scene work folder>",
"content": "/Game/.../<Name>"} - and the tools read it as U2UE_SCENE_NAME / _DIR / _CONTENT / _UNITY.

parity

the game's rules on every runtime they run on, compared by float bits with a characterised allowance.

u2ue parity - do the game's rules give the same answers on every runtime they run on (BASICS sections 4-5).

    py -m u2ue --project <name> parity [--dir DIR] [--require ENGINE ...] [--characterise]

A port that moves the rules into an engine-free model runs the SAME model on Unity (Mono) and on the Unreal host (CoreCLR), and a
headless runner beside them. Each run writes a digest: <dir>/logic-<Engine>.txt, one `key=value` row per case after a
`digestVersion=N` line, every float as its float32 BIT PATTERN in hex (Mono prints float "R" with 9 digits, .NET prints the shortest -
identical bits spell two ways; compare bits, never text). This wraps .opus-tools/logic_diff.py (the facade never rewrites a tool):
every row compared across every engine found; a difference is RED unless the characterised allowance (<dir>/logic-allowance.json,
written by --characterise from the reports on disk) pins that exact row to its exact bits AND to one ULP - so a new row, a moved
value or a wider gap stays red. Exit 0 agree, 1 a row differs, 2 refused (a required report missing, or digest versions differ).
The project names its digest folder as parity.dir; a project whose model has not run yet has none, and is refused.

digest

the game's rule cases answered with no engine: on CoreCLR (Headless) and on that Unity's own Mono (UnityMono).

u2ue digest - a game's rule cases answered with NO engine, on both runtimes a port has to agree across (logic-port skill step 9;
BASICS section 5): CoreCLR - what the Unreal host and a headless runner use - and that Unity version's OWN Mono. Nothing opens a
window and nothing takes focus. `u2ue parity` then marks the two answer sheets against each other by the bit.

    py -m u2ue --project <name> digest run --entry Ns.Class.Method --cases A.cs [B.cs ...] [--refs X.dll ...] [--dir DIR]
                                           [--editor UNITY_INSTALL]
    py -m u2ue --project <name> digest faithful
    py -m u2ue.verbs.digest --selftest              a fixture of its own (any game, any release)
    py -m u2ue.verbs.digest --selftest-reference    the reference project's recorded Editor / Headless digests

The entry is a static method returning the digest text (string) or a U2ue.Runtime.Digest. --refs defaults to the project's model:
every model layer built RELEASE for netstandard2.1 - the build Unity loads (plugin_sync_gate's canonical one) - and U2ue.Runtime.
The configuration is part of the answer: Mono keeps float intermediates wide wherever the IL leaves them on the stack, and a Debug
build's IL stores them to locals instead. MEASURED 2026-10-21 (TASKS D13): the seed-51 battle replayed on this Mono from a Debug
build forecast turns 18 and 19 unlike Unity; the same source built Release forecast all 27 as Unity did. --editor names the Unity install whose Mono
runs the cases (its folder name must be the project's unity.version); without it the project's unity.editor is read, and a
project naming neither is refused BEFORE either sheet is written. `run` writes, into DIR (default parity.dir):
  logic-Headless.txt    the cases compiled with the .NET SDK and run on CoreCLR (net8.0)
  logic-UnityMono.txt   the same cases compiled by that Unity's csc.exe and run on its mono-bdwgc.exe (the Editor's own runtime
                        build), with logic-UnityMono.provenance.json naming the Mono and whether it is MEASURED faithful
WHY UNITY'S MONO CAN STAND IN FOR THE EDITOR, AND ONLY WHERE MEASURED: a float rule's answer depends on the runtime that JITs it, and
Mono is the odd one out (it keeps float intermediates wider, so `a * b + c` can land one ULP from CoreCLR's). MEASURED 2026-10-16 on
Unity 6000.3.16f1: the reference game's digest (383 rows) computed this way equals the digest the Unity Editor wrote, row for row,
including the 35 rows where Mono and CoreCLR differ; and its CoreCLR run here equals the recorded headless digest.
  `faithful`  re-measures that: the project's "mono.faithful" block names the Editor that recorded a digest, the cases and DLLs it
              ran, and that digest. Exit 0 = identical; the measurement is written as a conformance bake
              (shared/conformance/mono-standalone-facts-<major.minor>.json, with unity.version) - the next `run` on that Unity reads it.
A Unity version with no such bake is labelled UNMEASURED in the provenance: Mono's answer, not yet proven to be the Editor's.

host

the game's OWN Unreal project, made as a customer makes one: create, install, compile, generate, wire, publish, run.

u2ue host - the game's OWN Unreal project, made by the toolkit step by step as a customer makes one (u2ue/hostproject.py:
HostProject; the u2ue-logic skill's step 10).

    py -m u2ue --project <name> host plan              every step: the command it runs and the line that proves it
    py -m u2ue --project <name> host status            each step's record (host-<step>.json): proven, failed, or not run
    py -m u2ue --project <name> host <step> [--dry]    run ONE step: create, install, compile, generate, wire, publish, run
    py -m u2ue.verbs.host --selftest

The Unreal steps (compile, generate, publish, run) REFUSE while the project's adapter says the Unreal host is busy, and when this
shell's PATH would hide .NET from UnrealSharp (run them from native PowerShell); each is judged by its proof line in its own log
(and `run` also by the digest file being written after the run started). Exit 0 = the step proved itself; 1 = it ran and did not;
2 = refused before it ran.

ui

a Unity UI screen converted to a folder Unreal reads; the generic uGUI / TextMeshPro library's tests.

u2ue ui - a Unity UI screen, captured, converted to a folder Unreal reads, and rebuilt by Unity's own layout rules.

    py -m u2ue --project <name> ui convert <capture dir> --screen NAME [--out DIR]
    py -m u2ue --project <name> ui test
    py -m u2ue --project <name> ui capture
    py -m u2ue.verbs.ui --selftest

  convert   one capture -> one screen folder: the capture itself, its sprites, and each TextMeshPro font's TTF located by the GUID
            the font asset recorded and PROVEN by identical glyph indices (a font that fails is refused). The project's Unity
            Assets are searched (unity.assets). DIR defaults to <work.ui>/screens/NAME when the project names work.ui. A DIR that
            exists must hold a screen.json: the converter replaces the folder it writes, so a folder it did not write is refused.
  test      the generic UI library's own tests (u2ue/runtime/U2ue.Ui.Tests, headless): uGUI's layout, meshes, raycast and
            TextMeshPro's layout held to Unity's captures, with no game reference.
  capture   runs in the project's own Unity Editor, in Play mode (it reads uGUI's resolved state and TextMeshPro's per-glyph
            layout). The reference capture is an Editor script behind a local HTTP bridge; for any other game it is planned to ship as
            the package's Editor assembly, which waits on installing the package into a project (the owner's decision) - refused
            here, by name.

The library is the converter's generic part (u2ue/runtime/U2ue.Ui); a game's panel bindings stay the game's. Nothing here
launches Unity or Unreal.

window

ONE Unity measurement window from a data file: idle-gated, owner-stoppable, nothing replaced, md5-held.

u2ue window - ONE Unity measurement window, from a data file (pillars 4, 10, 11). It replaces hand-cloned window scripts,
each made by search-and-replace on the one before (which broke once, on half-renamed frames).

    py -m u2ue --project <name> window check <spec.json>     every refusal judged now, nothing touched (exit 0 = it would start)
    py -m u2ue --project <name> window run <spec.json>       wait for the owner to be away, then run it
    py -m u2ue.verbs.window --selftest                       the whole flow against a SIMULATED editor - no Unity is touched

A SPEC (JSON) - what the window measures, never how it is kept safe:
    {"label": "g23", "why": "...", "probes": ["EffectPhotoProbe"],
     "inputs": [{"from": "<lane>/x6/effect-photo-list-x6.tsv", "to": "effect-photo-list-x6.tsv"}],      copied INTO the conformance dir
     "trigger": {"file": ".RUN_EFFECT_PHOTO", "lines": ["list:effect-photo-list-x6.tsv", "record:effect-photo-unity-x6.json",
                                                         "out:<the folder for the frames>"]},
     "outputs": ["effect-photo-unity-x6.json"], "wait_seconds": 900}
    "probe_src" (optional): a folder holding a REFERENCE build of an earlier probe, dropped instead of the toolkit's own - its
    PROVENANCE.json names the commit its files were taken at ("commit"), what was written onto them and why ("graft"), and every
    file the window drops ("files"): those exactly, no helper inferred. A folder without one is refused.
THE SAFETY, written once, here, for every window (the owner's editor is the owner's):
  - starts only after 600 s with no cursor move and no key or button (lane/wait_quiet.ps1 - its own QUIET line, nothing else), and a
    presence watch (lane/wait_presence.ps1) stops it at its next step when the owner returns: the probes are removed, nothing else runs
  - refuses: Play mode or no bridge, the editor lock held, an output that already exists (nothing is replaced), the trigger already
    down, a DIFFERENT file already where an input goes, a probe already in the Editor folder, a probe that does not compile HEADLESS
  - holds the editor lock (.opus-tools/.locks/unity-editor.lock) for its whole life; md5s every conformance record (but its outputs)
    and the project's guard files before and after - a change is a FAIL; the console reset before (nothing changes if it cannot be)
    and judged after, an editor mid-reload asked again (editorlink.judge_console) and a console never read a FAIL
  - drops each probe with a last comment line unique to the drop, so the editor compiles it even when it never saw an earlier
    window take the same file out (10-20)
  - deletes the probes only while the editor is idle (twice, 5 s apart: an earlier window deleted them mid-import) and waits until the editor DLL no
    longer holds their names
  - never answers a modal, never enters Play, never runs the Test Runner
The project names: unity.root, unity.probe_dir (the Editor folder probes are dropped into), unity.guard (files whose md5 must hold),
unity.probes - "copy" (each probe is dropped into probe_dir for the window and taken out again) or "package" (the installed u2ue
package's Editor assembly holds them: nothing is copied, and every probe the spec names must be in that assembly) - and unity.link,
how the editor is asked its state, a recompile and its console (u2ue/editorlink.py): "http" (the game's own bridge on
bridge_port.txt) or "channel" (the package's EditorChannel, through the channel folder below; STORE-3c). Before the trigger
the runner names its channel - the conformance folder - in <unity.root>/UserSettings/U2ue/channel.txt, which every probe reads
(ProbeChannel), and puts that file back as it found it afterwards (STORE-3b, 10-20).

trial

a route's TRIAL in Unreal from a data file: build, resave, read, judge, photos; one Unreal at a time, stoppable.

u2ue trial - a route's TRIAL in Unreal, from a data file (pillars 4, 10, 11). It replaces hand-copied queue scripts
(lane/queue_*.ps1, one near-identical block per trial): the trial is data, and the runner is written once.

    py -m u2ue --project <name> trial plan <spec.json> [...]     every command and variable each step would run - nothing runs
    py -m u2ue --project <name> trial run <spec.json> [...]      run them in order; one Unreal at a time; stoppable between steps
    py -m u2ue --project <name> trial stop                       ask the running trials to stop at their next step boundary
    py -m u2ue.verbs.trial --selftest                            the runner against a SIMULATED executor - nothing launches

A SPEC (JSON) - what the trial tries, never how it is run:
    {"label": "rc1", "why": "...", "dir": "{lane}/ratecurve/rc1", "root": "/Game/<Game>/Trials/RC1",
     "requires": {"file": "{vfxport}/build_niagara.py", "contains": "# WARMBURST \(10-16"},       optional: unmet = SKIPPED, said
     "keys": {"file": "{dir}/keys.txt"} | {"list": ["prefab.<guid>", ...]} | {"script": ["{lane}/x/keys.py", "{dir}/keys.txt"]},
     "switches": {"VFXPORT_RATECURVE": "1"},                                    set for the BUILD only, removed after it
     "steps": [{"build": {"batch": 6, "max_seconds": 9000}}, {"resave": {"max_seconds": 3600}},
               {"read": {"frames": 90, "max_seconds": 3600, "out": "rb_rc1.json"}},
               {"judge": {"argv": ["{lane}/ratecurve/ratecurve_check.py", "{dir}/rb_rc1.json"]}},
               {"photos": {"times": [0.1, 0.3, 0.6, 1.0], "max_seconds": 3600}},
               {"py": {"argv": ["{lane}/meshvcol/trial_sheets.py", "{label}", "{photos}", "{root_dir}", "--all"], "unreal": false}}]}
  placeholders: {dir} {root} {label} {lane} {effects} {tools} {vfxport} {photos} (= <effects>/photos/<label>) {root_dir} (the
  content root on disk: <uproject dir>/Content/<root after /Game/>)
THE STEPS, each the same commands and variables a hand-written queue ran:
  build    fx17_build.ps1 -KeysFile <dir>/keys.txt -Tag <label> -Batch N -MaxSeconds S, with the switches, U2UE_CONTENT_ROOT=root,
           U1E_BUILD_NEWEST / U1E_BUILD_REFUSED in <dir>; its u1e-build-only.json copied to <dir>/build-only-<label>.json - no record,
           or nothing BUILT, ends the trial; a key asked for that the record does not hold (the build's own -MaxSeconds stopped it)
           is NAMED in <dir>/unbuilt-<label>.txt - a delta trial's keys file - and the trial is PARTIAL, its built keys still read
           and photographed. Size S from the measured rate: about 45 min per batch of 6 heavy (mesh) keys on the reference host.
           A trial whose root IS the project's content root is a DELTA - a flipped route's keys rebuilt where the game plays them -
           and its build is TAKEN into the acceptance in this same step (u2ue/acceptance.py): the record copied into the records
           dir and every BUILT key's acceptance override pointed at it; a take refused by name FAILS the trial
  resave   u1e_py.ps1 -Script u1e_resave.py with U1E_RESAVE_PKG=root; "only": "built" resaves just the systems this trial built
           (U1E_RESAVE_ONLY - a delta into a shared root: the content root's 618 systems take 78 min). Judged by its record
           (u1e-resave.json, kept as <dir>/resave-<label>.json), never its exit: no record, an error, or a built system not
           saved STOPS the trial (FAIL) - a read or photos would run it stale
  built    no build: the systems already under the root, one per key (a read of an existing build - u2ue conform)
  read     u1e_py.ps1 -Script u1e_color_size_readback.py with U1E_RB_SYSTEMS = the BUILT systems, U1E_RB_FRAMES (and U1E_RB_DT
           when "dt" is given); copied to <dir>/<out>
  judge    py <argv> [with "env"] - its exit and last lines are the trial's verdict (a red judge is FAIL; the photos are still taken, to LOOK at);
           "plant": {"argv": [...]} runs the same judge on a record it MUST refuse - a plant that passes FAILS the step
  photos   u1e_py.ps1 -Script u1e_fx_photo.py with U1E_PHOTO_SYSTEMS, U1E_PHOTO_TIMES, U2UE_PHOTOS_DIR=<photos> - judged by its
           Capture (u2ue/capture.py), never its exit: a system or frame missing PARTIAL and named, no result FAIL
  unreal   any other Unreal script: u1e_py.ps1 -Script <script> with its "env"; its "out" (in the effects dir) copied to <dir>, none
           written FAILS (a probe that builds in memory, e.g. u1e_trail_real_probe for what a built system trims)
  py       any other tool (a reader that runs Unreal itself: "unreal": true waits for no Unreal first and names the runner as host)
THE RULES, once: runs alone (no lane queue, no other trial); waits for no Unreal before every Unreal step; the inherited VFXPORT_ /
U1E_ / U2UE_ variables are dropped and the project's loaded (Project.env); refuses a PATH whose dotnet marker lacks the trailing
backslash UnrealSharp needs (the Bash chain: launch from native PowerShell); a STOP file is read between steps and between trials -
a stop never kills a step mid-way (only the runner can stop cleanly).
The trials run from a SNAPSHOT of the code parts (u2ue/run.py Run): `run` copies them, then runs the trials in
a child process whose U2UE_PART_* point at the copies - an edit to the live converter mid-queue cannot change what runs. The record
<dir>/trial-<label>.json names every step's verdict, the copy it ran ("run") and the commit of each toolkit tree it was taken at.

conform

data-first conformance over all keys: Unity's particle state (one generic probe) against Niagara's readback, paired by file id.

u2ue conform - DATA-FIRST conformance over all keys at once: Unity's own particle state, read per system by the
generic probe, against what the built Niagara systems compute, read back - paired by the prefab's system file id, judged on numbers.
Why: on the reference port, ONE class-wide readback found a rule (every non-prewarmed burst born one warm-up tick late) that nights of
per-effect photos had missed; this makes that readback a standing check.

    py -m u2ue --project <name> conform cases --name <run> [--keys FILE] [--times 0.1,0.3,0.6,1.0]
        writes, from the project's IR: <conformance>/<run>-cases.json (one ParticleCaseProbe case per key: its prefab placed by the
        game's effect spawn, seed pinned, read from a restart at each time), lane/windows/<run>.json (the Unity window that runs it)
        and lane/trials/<run>-read.json (the Unreal read of the same keys' BUILT systems at the probe's step, 0.02 s)
    py -m u2ue --project <name> conform diff --unity <particle-cases record> --unreal <readback record> [--report FILE]
        per key, per active emitter: the live COUNT at every probe time and the FIRST BIRTH (time minus the oldest age, both sides),
        Unity's system found by its file id, Unreal's emitter by the converter's own naming (niagara_names.system_names)
        --report writes the rows (each with the emitter's file id and the numbers judged) STAMPED with the judge's id and inputs
    py -m u2ue --project <name> conform latest [--run NAME] [--dir DIR]
        the newest stamped report under <lane>/conform of ONE run (its Unity record NAME-unity.json; the project's
        conform.standing_run unless --run): "CONFORM OK n of m (x %)" - STALE (exit 1) when another judge made it
    py -m u2ue --project <name> conform classes --report FILE [--build u1e-build-newest.json]
        every LATE / EARLY row NAMED by the converter's own note on that emitter or a measured signature (NAMED_MISSES), only
        when direction and size agree - the rest UNNAMED, listed: the work
    py -m u2ue.verbs.conform --selftest      identical records agree; a planted 0.03 s late birth FAILS; a count off FAILS; an
                                             emitter missing on one side is named, never dropped
VERDICTS per emitter, both sides read at Unity's sample times only (like with like): OK (a "sub-frame" note when the births
differ inside one frame) | LATE / EARLY (first DRAWN on a different frame) | COUNT (more than max(1, 5 %) apart at a time, or only
one side drew anything at the times read) | BIRTH UNREAD (the counts agree and no first birth can be read: an infinite lifetime, a capped list) |
UNPAIRED (one side has no such emitter - named with the side) | NO DATA (neither side
drew a particle at the times read: an emitter alive only between samples is not judged, and is counted as such).

judge

every judge the trials run, the trials that run it, and whether its plant can refuse (its --selftest, or a trial's declared plant).

u2ue judge - every judge the project's trials run, the trials that run it, and whether its plant can refuse (u2ue/judge.py: Judge).

    py -m u2ue --project <name> judge             each judge: selftest / declared (a trial's plant) / NO PLANT
    py -m u2ue --project <name> judge --prove     runs each judge's --selftest; exit 1 when one fails or a judge has no plant
    py -m u2ue.verbs.judge --selftest             the Judge class's own selftest
A judge with no plant has only ever passed, which is indistinguishable from a judge that was switched off (pillar 5).

extract

Unity prefabs -> the engine-neutral IR (no editor runs).

u2ue extract - a Unity project's effects -> the engine-neutral IR.

    py -m u2ue --project <name> extract [--steps index,keys,ir,missing,alphadilate] [--out DIR] [--resolve FILE]

Steps, in order, each one's output the next one's input:
  index   the guid index (t1_guid_index.py)                                     -> work.guid_index
          + when the project names its Editor (unity.editor): the built-in shader names (u1e_builtin_names.py)
                                                                               -> work.effects/builtin_extra_names.json
  keys    the project's effect keys, from its ADAPTER (u2ue/adapters)            -> work.resolve
            unity_project     every prefab that holds a ParticleSystem (u2ue/keys.py), Unity's spawn rule
            <game>            a game adapter (u2ue/adapters/<game>.py): the keys the game's own code fires, its pool's spawn rule
          then checked: every key agrees with the adapter's spawn rule (u1e_ir picks the rule by the key's prefix)
  ir      one IR file per READ key (u1e_ir.py)                                  -> work.effects/ir + u1e-ir.json
  missing every material / shader / texture reference of the IR that no .meta of the project carries (u1e_missing_assets.py)
                                                                               -> work.effects/missing-assets-facts.json
          - the build reads it (u1e_slots: an emitter whose every drawn slot is absent is EMITTER-ABSENT by name); F27, 10-21:
          no verb ran it before, so a new project's build died opening it
  alphadilate  Unity's stored RGB under each alphaIsTransparency texture's transparent texels, READ off the project's own imports
          in Library/Artifacts (u1e_alphadilate.py)                             -> work.effects/alphadilate/alphadilate.json
          - every such texture READ (a derived file), NOTHING (no fill to carry) or REFUSED by name (no artifact: imported as the
          file is); the build's import requires the manifest. F30, 10-21: no verb ran it before, so a new project's every such
          texture was refused at import, its material with it

  --out DIR       the IR and its summary go under DIR instead of work.effects: a staging run that leaves the project's IR alone
  --resolve FILE  the keys are read from FILE instead of work.resolve (a sample); the keys step cannot run with it

The run is defined by the project file and these flags only: U1E_* and VFXPORT_* variables inherited from the calling shell are
REMOVED (and named) before any tool starts - a switch left over from another run must not change an extraction.

Checked after the ir step, exit 1 on any:
  every READ key of the resolve is in the summary, as an IR file or a NAMED refusal - none dropped
  every IR file is on disk and parses, with its emitter count
  every "Assets/..." path an IR names exists in THIS project's tree (a path from another project's index cannot pass)

check

the toolkit's selftests, the project's field gates, the measured rules' Unity versions.

u2ue check - is the bag sound, and does this project's IR meet every field gate.

    py -m u2ue --project <name> check [--only selftests|gates|facts|model] [--tool NAME ...]

  selftests  every tool's OWN offline selftest (u2ue/selftests.py SelftestRegistry - read off each tool by hand, none invented
             here), then the project file's own rows (`selftests`: the gates written against that one game); each must exit 0; in a
             release, a row whose tool the release kept out is NOT RUN with the release's own reason (RELEASE-excluded.tsv); run with
             the inherited U2UE_ / U1E_ / VFXPORT_ variables dropped (a PIN kept, tools.clean_env) and the project's own U2UE_ paths
             set, so no switch left in a shell can change what a plant meets. A selftest that is never run
             here says its measured reason (NOT_RUN, or the project's not_run). v4_write_gate's --selftest also runs its STATIC gate, which
             types only part of the converter's writes: its PLANTS must bite ("SELFTEST PASS"); its gate result is not counted - the
             authority on refused writes, v4_msg_gate over the built packages, runs per trial.
  gates      yaml_field_gate over THIS project's IR (every key of every enabled module read by shuriken_ir or excused with the values
             it may take) and ir_field_gate (every field the IR carries named by the converter or DELIBERATELY_UNREAD with its reason)

  facts      every measured Unity rule with the Unity version it was measured on, against the project's unity.version: a rule
             measured on another version is named UNVERIFIED for this project (reported, not a failure)
  model      layer_gate and host_gate on the engine-free model the project names (model.*); a project with no model is told so

Exit 1 when any one fails. Nothing launches Unreal or Unity; below normal priority.

build

IR -> Niagara systems under the project's content root (Unreal, headless).

u2ue build - the project's effect IR -> Niagara systems under its content root.

    py -m u2ue --project <name> build [--keys FILE] [--tag TAG] [--batch N] [--no-resave] [--dry]

  keys     every READ key of the project's resolve with an IR file (not refused) - or the list in FILE (comma / newline separated)
  steps    the asset-name table (fx17_asset_names.py: names two different Unity files would share, per project) -> records/
           asset_names.json; then fx17_build.ps1 -KeysFile -Tag -Batch [-Resave] - u1e_build in headless Unreal, batched compiles,
           the resave, the record kept as records/u1e-build-<TAG>.json
  --dry    print the plan (keys, paths, the guard's verdict) and run nothing

Refuses while the Unreal host is busy (the project's adapter answers: any Unreal running, or the game's own queues - verbs/_ue.py). The tools read
the project's U2UE_* environment; U1E_* / VFXPORT_* variables inherited from the shell are REMOVED and named,
so the build is the project's defaults - the build an acceptance rebuild makes.

read

the built systems read back frame by frame (Unreal, headless).

u2ue read - read back the systems a build made, frame by frame.

    py -m u2ue --project <name> read [--tag TAG] [--frames N] [--dry]

Every BUILT system of records/u1e-build-<TAG>.json is simulated headless in Unreal and its particles read per frame
(u1e_color_size_readback.py through u1e_py.ps1: position, velocity, colour, size, age ... at 1/60 s steps) into
records/rb_<TAG>_<N>.json - the input every read-back check of the bag takes - with its capture summary (u2ue/readback.py): a
system that captured no frame, or fewer than asked, is named and the verb exits 1. Refuses while the Unreal host is busy.

photo

the built systems photographed, paired with Unity's frames (Unreal, headless).

u2ue photo - photograph the systems a build made and compose the Unity / Unreal pair sheets.

    py -m u2ue --project <name> photo [--tag TAG] [--times 0.1,0.3,0.6,1.0] [--dry]
    py -m u2ue --project <name> photo --unity-list FILE [--times ...]

--unity-list writes, and runs nothing else, the list Unity's EffectPhotoProbe reads (leaf, prefab, times, "hdr"; its Unity run is
the project owner's call) for every key of the project's IR summary: the leaf is the system's (keys.system_leaf), the name Unreal's
frames carry, so the pair sheets match them; the prefab is the IR's own "source". A key whose IR file is not its system leaf, or
whose IR names no prefab, is refused by name (F33, 10-21: the store sample's Unity frames were named by its prefab and paired with
nothing).

Every BUILT system of records/u1e-build-<TAG>.json is drawn headless at each time (u1e_fx_photo.py through u1e_py.ps1, the
project's photos/unreal), then u1e_photo_sheet.py pairs each with Unity's frames where the project has them (photos/unity_hdr,
taken by EffectPhotoProbe in that project's own Editor - a Unity run, the project owner's call) into photos/sheets. A sheet is
evidence only once LOOKED AT. Refuses while the Unreal host is busy.

The run is judged by its CAPTURE (u2ue/capture.py), never by the tool's exit: the result record is kept beside the frames, and a
system with no judgeable frame (an error, no background, no frame) or a frame asked for and not written by THIS run is named; a system never
captured fails the verb.

report

the acceptance page from the project's records.

u2ue report - the acceptance report for a project, built from ITS records.

    py -m u2ue --project <name> report [--out FILE]

Runs report_build.py - the acceptance page's own builder - with the project's U2UE_* environment: the IR summary,
the build records, the sweep and the photo sheets are read from work.effects / work.records, and the page names the project. The
default page is <work.effects>/report/<name>_acceptance.html. A decision's evidence picture shows only when the report holds the
key it pictures. Nothing launches Unreal or Unity; below-normal priority.

The report reads what is THERE: a key never built reads "never built", a sweep or a photo screen not run reads absent - so a
project's first report, before any build, already names every key it will have to account for.

The run is defined by the project file and these flags only: U1E_* and VFXPORT_* variables inherited from the calling shell are
REMOVED (and named) first, as extract does.

metrics

the port's numbers, each from a record, with its definition.

u2ue metrics - the port's numbers for a project, every one COMPUTED FROM ITS RECORDS with its denominator and its definition.

    py -m u2ue --project <name> metrics [--json FILE]

Nothing here is estimated, sampled or remembered: a number this verb cannot compute from a record on disk is printed ABSENT with
the record it needs, and a tool that stops stops this verb. Each input's age is printed, and an input OLDER than the newest build is
marked STALE (it describes builds that are gone) - a stale number is never presented as current.

The emitter numbers are the ACCEPTANCE PAGE's (lane/report_build.py, run here with the project's environment), never recounted
here. The page picks each key's record (an acceptance override, else the acceptance rebuild's chunk, else the newest build, else a
trial), counts a log as drawn only when it carries modules, and applies the measured never-fires rule over whole sub-emitter chains
(fx17/unity_never_fires.json). A recount of the newest records that skipped those rules (skipped logs counted as drawn, the chain
rule missed) was measured wrong both ways, which is why this verb never recounts.

THE DEFINITIONS (they are the claim; a number quoted without its definition is not one):
  keys        the project's effect keys (its IR summary), each with the verdict of the record the page chose for it
  drawn       an emitter whose log carries modules - it draws in Unreal
  absent      an emitter the build named EMITTER-ABSENT, split by the page:
                as Unity - absent exactly as in Unity, each by a MEASURED or READ rule in the converter's own words (the game
                           never starts it; Unity never fires it - measured; Unity draws / emits nothing there itself; a missing
                           material Unity has no particle to draw on) - no gap
                gap      - every other: Unity draws it, Unreal does not - a NAMED gap; charged to its ROOT (an absent parent's
                           children to the ancestor absent for its own reason), so a root's count is what porting it brings back
  coverage    drawn / (drawn + gap) - of the emitters Unity draws, the share Unreal draws
  measured    drawn emitters with no "SUBSTITUTED" note - drawn by a rule measured against Unity, not a named stand-in
  data        the readback sweep (checks_summary.json): per check, emitters checked and FAILs, summed over every part
  image       the photo screen (u1e_sheet_screen over the sheets listing): pairs compared, pairs flagged for a big difference,
              and of the flagged how many carry a ONE DRAW (RANDDRAW) or GRIDTICK label - frames where a difference is the
              capture, not the port
  machine     the chosen records' own per-key seconds (delete .. finalize), summed and per key
  routes      the converter's verified switches (patch_flip_defaults' TABLE, DISTINCT switch names - one switch read in two files
              has two rows) flipped default ON with their evidence, and the switches named deliberately OFF (flip_audit's
              DELIBERATE_OFF, each with what it waits on)
Agent tempo (how long a route took the agent from FOUND to FLIPPED) is not in these records - it is the git history's, and is
reported by `u2ue tempo` when that exists, never folded in here.

tempo

each verified route's first code -> verified flip, read off git.

u2ue tempo - how fast the toolkit's verified routes went from first code to verified flip, read off git.

    py -m u2ue --project <name> tempo [--json FILE] [--since YYYY-MM-DD]

THE DEFINITION (it is the claim):
  a route    one switch of patch_flip_defaults' TABLE (distinct names; a switch read in two files has two rows) - each one was
             written default OFF, proven, trialed and flipped default ON with its evidence row
  first code the earliest commit, over every file the switch's rows name, whose ADDED lines carry the switch name
  flipped    per file, the earliest commit whose added lines carry its default-ON read (environ.get("NAME", "1")); the route
             is flipped when its LAST file is - and only if EVERY file reads it default ON today (a TABLE row is evidence a switch
             may flip, not proof that it did: a switch held OFF can have a row and still read "0")
  tempo      flipped - first code, in hours of wall clock (commit author times). A route whose first code already reads it
             default ON (no OFF stage on record) is counted apart, never as tempo 0.
What this does NOT measure, said so it is never implied: the time from FOUND (the defect first seen) to first code, the
agent's tokens, and the machine's build hours (`u2ue metrics`). A file whose history holds no default-ON line names the route
ABSENT here, with the file - never a guessed date.

cycle

every pillar of the product checked: PASS / FAIL / HELD by a named decision / ABSENT (no check yet).

u2ue cycle - every pillar of the product checked, the way it is checked every work cycle.

    py -m u2ue --project <name> cycle [--pillar N ...] [--dry]
    py -m u2ue --project <name> cycle --commit    the commit gate (CommitGate): the commit-marked checks, when a toolkit file is
                                                   staged - the toolkit repo's pre-commit hook (install_commit_gate.sh)
    py -m u2ue.verbs.cycle --selftest

Each pillar (u2ue/pillars.py) runs its checks; the record goes to <records>/cycle-<stamp>.json and cycle-latest.json, and the NEXT
cycle reads it for every Trend (a number that must not move the wrong way). Exit 1 when any pillar is FAIL - red stops the cycle.
An ABSENT pillar is not a pass: it names the work that would give it a check.

tool

one tool of the toolkit run by hand, found by its file name, with the project's variables (u2ue/env.py).

u2ue tool - one tool of the toolkit, run by hand with the project's U2UE_* variables. A tool reads its paths only from
those variables (u2ue/env.py) and refuses without them, so this is how a tool is run outside a verb.

    py -m u2ue --project <name> tool <tool.py | tool.ps1> [args ...]
    py -m u2ue --project <name> tool --selftest

The tool is found by its FILE NAME in the toolkit's parts (u2ue/tools.py PARTS); a name in none of them, or in more than one, is
refused with what was found. A .py runs on this Python, a .ps1 on PowerShell 7 - both below normal priority, in the tool's own
folder, their output streamed through and their exit code returned. A tool that starts Unreal keeps its own guards (one Unreal at a
time); `tool` adds none and removes none.

release

the package as a repo: assembled from the toolkit's own trees by one manifest, secrets refused, public readiness counted.

u2ue release - the package as a repo, assembled from the toolkit's own trees by one manifest (u2ue/release.py: Release).

    py -m u2ue release --to <DIR> [--dry]     assemble the repo into DIR (empty, or a release checkout): what ships, what is left
                                              out and why, the public-readiness count; --dry writes nothing
    py -m u2ue release --check --to <DIR>     exit 1 when DIR differs from what the manifest would write (a stale release)
    py -m u2ue release --store [--compile] [--to <DIR> --namespace <NS>] [--dry]
                                              the Unity half as an Asset Store UPM product (StorePackage): every store rule's count;
                                              --compile (with --project) adds 1.1.b, the package's C# compiled ALONE against the
                                              project's editor - Unity's own assemblies and nothing of the project (PackageCompile);
                                              with --to, the package written - only when every count is 0, it compiled, and the
                                              publisher namespace (from the publisher's UPM enrolment) is given; --dry writes nothing
    py -m u2ue release --store --classic --compile [--to <PROJECT>/Assets] [--dry]
                                              the same files as a CLASSIC Asset Store package (StoreLayout CLASSIC): ONE folder
                                              u2ue under a Unity project's Assets, no package.json and no namespace, the manual and
                                              the sample ordinary folders with their metas - written only when every count is 0 and
                                              it compiled, into an empty folder; the Publishing Tools' Uploader exports it
    py -m u2ue.verbs.release --selftest       a planted secret refuses; a run record, an image and an oversized file are named out;
                                              a planted game name is counted; a second assembly writes nothing; drift is caught;
                                              each store rule refuses its own plant; no package without a namespace or a compile;
                                              the standalone compile leaves out each thing a project adds and refuses what it
                                              cannot tell apart (a planted compiler stands in for Unity's)

Exit 0 = assembled (or current); 1 = --check found a difference; 2 = refused (a secret, a folder that is not a release, no --to).
Nothing is committed or pushed: the repo's history and its remote are the owner's.

blueprint

the Blueprint view (a quarantined experiment): a Blueprint's text to code, every node traced to its use case step and requirement, a 3D city; doctor and install its prerequisites; its tests on real data.

u2ue blueprint - the Blueprint view (the toolkit part `blueprint`): C# and Unreal Blueprints read into one graph language and
printed back as either, a Blueprint's text converted to code with every node traced to the use case step and the requirement it
serves, drawn as a 3D city. No project needed.

    py -m u2ue blueprint doctor                 every prerequisite: found (with its version) or missing (with the command that installs it);
                                                Unreal is the engine UE_ROOT names, or with --project <name> its unreal.engine
    py -m u2ue blueprint install [--yes]        the install commands for what is missing - only PRINTED unless --yes; nothing is
                                                installed silently, and what cannot be scripted (Unreal) is said
    py -m u2ue blueprint test [--quick] [--offline] [--allow-missing]
                                                the critical parts on REAL data (tools/test_real.py): the online paste, Epic's template
                                                exports, the game's own code - each held to a count taken another way, each with a plant
    py -m u2ue blueprint build <set dir> "<title>"   a paste set end to end: convert, trace, classes, the model's spaces, the 3D data,
                                                then the closed loop (every requirement's effect held to the code) and its report
    py -m u2ue blueprint gates                  every gate and measure of the experiment (names, orphans, models, frictions, retrieval)
    py -m u2ue blueprint view                   how to open the page and the 3D city
    py -m u2ue blueprint showcase <out dir>     the showcase page and the city beside it, every figure read from the results
    py -m u2ue blueprint package <out.unitypackage> [--unity <Unity project>]
                                                the Unity package (Window > u2ue > Blueprint View), built without Unity and checked;
                                                with --unity its C# is compiled alone against that project's editor
    py -m u2ue blueprint --selftest             doctor's own check: a prerequisite that is not there is reported missing, with its command

The owner, 10-28: "we will be folding this in with u2ue as an additional tool. So make sure it can install what is needed if need be",
and later the same night "update the u2ue with the new features for blueprints". The part ships in every release (`u2ue release`,
at <release>/blueprint); this verb is the toolkit's one way in, as for every other tool. The C# reader also reads a Unity project
the way Unity compiles it, from the command line Unity wrote (`--rsp`).

21. Reference

Who this is for: the toolkit developer and the reviewer - the file formats, environment variables, converter switches, tools and selftests, in one place to look them up. Read it when a field, a variable or a switch is named elsewhere and you need its meaning.

The tables marked generated are written by u2ue/manual/build.py from the code, so they change when the code does. Edit the code, not the table.

File formats

The project file - u2ue/projects/<name>.json

field type meaning
name string the project's name; also names the default report page
adapter string unity_project, or a game adapter's name (Chapter 18)
unity.root path the Unity project's root
unity.assets path its Assets folder
unity.version string its Unity version, e.g. 6000.3.16f1; measured rules are checked against it
unity.editor path, optional that version's Editor install, for built-in shader and material names
unity.probe_dir, unity.guard path, paths the Editor folder under the Unity root a probe is dropped into for one window, and the files whose md5 must hold across it (Chapter 8)
effects.key_source object {"kind": "particle_prefabs", "roots": [...]}; the only other kind the loader accepts is the reference port's own resolver
unreal.uproject path the Unreal host project
unreal.engine path the engine install
unreal.content_root string where built systems go, e.g. /Game/U2UE/<Name>
unreal.host object, optional the game's own Unreal project made by u2ue host: template, plugins, toolkit_plugins, sdks_root, digest (Chapter 13)
work.* paths effects, ir, guid_index, resolve, records, photos, inventory, and optionally materials (the material-parent tools' reads and outputs): where each step writes
code.roots paths the game's own C# folders, relative to the Unity root
model.root path the folder holding the engine-free model's projects
model.layers object {project: [projects it may reference]}, inner layer first
model.scan, model.hosting paths where platform members may not be declared, and the one folder where they may
model.hosts object, optional {engine: [folders holding that engine's host code]}, which the seam report reads (Chapter 5)
model.unreal_links bool, optional whether the layer gate also checks the Unreal host's links
parity.dir, parity.engines path, list where each runtime writes logic-<Engine>.txt, and which runtimes to compare
mono.faithful object, optional what digest faithful re-runs on Unity's own Mono: editor, entry, cases, refs, reference (Chapter 5)
scene object, optional the scene u2ue scene ports: unity, name, dir, content (Chapter 6)
conform.standing_run string, optional the conformance run conform latest reads unless --run names another, and the one the cycle trends (Chapter 9)
estimate_basis object, optional the port's own transcripts and runs, which token_basis.py reads to measure the token rates u2ue estimate multiplies by (the cost page)
selftests object, optional the game's own gates, runs and not_run (the selftest list below)
public_names object, optional names: the game's own names; the manual's build refuses a page holding one, and u2ue release counts the shipped files that do

The IR - one JSON file per effect key

Written by extract (u1e_ir.py over shuriken_ir.py), engine-neutral: nothing in it names an Unreal type. The reader writes to <work.effects>/ir while the gates and the build read work.ir, so work.ir must name that folder; a project file whose work.ir names another is refused when it loads.

field meaning
key, source the effect key and the prefab it was read from
rootRotation, rootScale the effect root's transform
emitters[] one entry per ParticleSystem: name; the main module (duration, looping, prewarm, startDelay, simulationSpace, scalingMode, playOnAwake, maxParticles, startLifetime, startSpeed, startColor, startSize and its axes, startRotation, gravityModifier, ringBufferMode, ...); modules (every other enabled module), emission, shape and renderer; the emitter's place in the transform chain (prefabPos, prefabRot, localScale, localRot, nodeMatrix, lossyScale, ownerScale, chainSheared); and the reader's own bookkeeping, prefixed _ (_active, _psFileID, _depth)
materials every material the emitters use, its shader and values (a variant's through its parent)
emitterCount how many emitters the effect holds
naturalLengthSeconds, naturalLengthWhy, peakSeconds how long the effect runs and when it peaks, with the reason
lifetimeSeconds the lifetime the game's code gives one spawn, or null; the reason is lifetimeWhy in the summary u1e-ir.json. Always null for a unity. key, whose game code is not read

A value Unity stores as a curve or a random range is an object, never a flattened number: {"mode": "constant", "scalar": 5, "value": 5, "readAs": "scalar (minMaxState 0)"}, where readAs says how the reader read it. yaml_field_gate and ir_field_gate (Chapter 9) hold the IR to the Unity fields on one side and the converter on the other.

The build record - records/u1e-build-<TAG>.json

Top level: package, keys, materials, meshes, textures, errors, vm1Errors (the material-parent author's), parents and the caches. Per key: key, prefab, ir, asset, shaders, seconds, emitters, saved, absentEmitters (each with its reason), converterErrors, converterWarnings, paramMisses and the verdict. The report and the metrics read only these records.

A measured fact file - shared/conformance/*.json

Written by a probe (Chapter 8): format (which ties the file to its probe, Chapter 18), unity (the version that ran it), the case's own parameters, and the raw values it observed under names the probe chooses (samples, shots, cases, ...). An error field when the probe could not finish. Never edited by hand and never replaced by a later bake: a new bake is a new file.

A parity digest - <parity.dir>/logic-<Engine>.txt

A digestVersion=N line, then one key=value row per case. Every float is written as its 8-hex-digit bit pattern. The allowance file (logic-allowance.json beside them) pins a characterised difference to its exact row and bits.

Environment variables

variable meaning
U2UE_TOOLKIT_ROOT resolve every toolkit part to <root>/<part> (the release layout)
U2UE_HOME exported to every tool: the folder that holds the u2ue package, which a tool adds to its import path to read the project through u2ue/env.py
U2UE_PART_<NAME> exported to every tool: each toolkit part's folder, as part() answers it. Set by hand, it points that one part at a copy (a pinned run)
U2UE_* (others) set by the facade from the project file for each tool it runs (U2UE_UNITY_ROOT, U2UE_IR_DIR, U2UE_EFFECTS_DIR, ...)
VFXPORT_<NAME>, U1E_<NAME> the converter's and the reader's route switches (below). The facade removes, and names, any set in the calling shell, so a run is defined by the project file and its flags only

Converter switches (generated)

Each switch is one converter route (Chapter 7). "Default today" is what the converter reads when the variable is unset. A trial's switches block (u2ue trial, Chapter 20) can still set one to 0 for an A/B. Each switch was flipped on only with an evidence row: the trial, the Unity measurement and the check that held on the reference port. Those rows, kept in the flip table, are the converter's audit trail; py -m u2ue find <SWITCH> prints them. A switch still OFF is not verified yet, and it stays OFF until a trial proves it.

102 distinct switches in the flip table (vfxport/patch_flip_defaults.py), 99 read default ON today.

switch default today read in evidence rows
U1E_ALPHADILATE_V2 ON u1e_alphadilate.py 1
U1E_HV_SUBUV ON u1e_hovl.py 1
U1E_MESHVCOL ON u1e_fbx.py, u1e_unitymesh.py 2
U1E_PSDTEX ON u1e_build.py 1
U1E_SHADER_EMITTER ON u1e_build.py 1
U1E_UC_BUILTIN ON u1e_build.py 1
U1E_UM_SUBUV ON u1e_ubermatcap.py 1
VFXPORT_ABSENTDRAW ON build_niagara.py 1
VFXPORT_ALIGNMESH ON build_niagara.py 1
VFXPORT_ALPHADILATE ON u1e_build.py 1
VFXPORT_AMESH ON build_niagara.py 1
VFXPORT_ARCSPREAD ON build_niagara.py 1
VFXPORT_BILLMESH ON build_niagara.py 1
VFXPORT_BILLSPIN ON build_niagara.py 1
VFXPORT_BUILTINMIPS ON u1e_build.py 1
VFXPORT_BURST0 ON build_niagara.py 1
VFXPORT_BURSTLAG ON build_niagara.py 1
VFXPORT_CULLFRONT ON vm1_author.py, vm1_hlsl.py, vm1_hlsl2.py 3
VFXPORT_DONUTLOOP ON build_niagara.py 1
VFXPORT_EDGEBURST ON build_niagara.py 1
VFXPORT_EDGEBURST5 ON build_niagara.py 1
VFXPORT_EDGELOOP ON build_niagara.py 1
VFXPORT_FIXALPHA ON build_niagara.py 1
VFXPORT_FORCESCALE ON build_niagara.py 1
VFXPORT_FPFOLD ON build_niagara.py 1
VFXPORT_FPRAND ON build_niagara.py 1
VFXPORT_FX16 ON build_niagara.py 1
VFXPORT_FX16C ON build_niagara.py 1
VFXPORT_FX16SUB ON build_niagara.py 1
VFXPORT_FX26 ON u1e_legacyparticle.py 1
VFXPORT_FX28 ON u1e_slots.py 1
VFXPORT_FX29 ON u1e_ubermatcap.py 1
VFXPORT_FX31 ON u1e_hstwosides.py 1
VFXPORT_FX32 ON u1e_hsblenddistort.py 1
VFXPORT_FX33 ON u1e_hsdissolve.py 1
VFXPORT_FX34 ON u1e_pilototoon.py 1
VFXPORT_FX35 ON build_niagara.py 1
VFXPORT_FX35_EVENT ON build_niagara.py 1
VFXPORT_FX35_ORBIT OFF - deliberately, not verified yet build_niagara.py 1
VFXPORT_FX35_WORLD OFF - deliberately, not verified yet build_niagara.py 1
VFXPORT_FX36 ON build_niagara.py, u1e_bursttrain_probe.py 2
VFXPORT_FX37 ON build_niagara.py 1
VFXPORT_FX37M ON build_niagara.py, vm1_author.py 2
VFXPORT_FX37S ON build_niagara.py 1
VFXPORT_FX37V ON build_niagara.py 1
VFXPORT_FX37W ON build_niagara.py 1
VFXPORT_FX9_STILL ON build_niagara.py 1
VFXPORT_GRAVCURVE ON build_niagara.py 1
VFXPORT_HBPIVOT ON build_niagara.py 1
VFXPORT_HOVLELEC ON u1e_hselectricity.py 1
VFXPORT_LIFECURVE ON build_niagara.py 1
VFXPORT_MESHRC ON build_niagara.py 1
VFXPORT_MESHSCALE1 ON build_niagara.py 1
VFXPORT_MESHSHAPE ON build_niagara.py 1
VFXPORT_MESHSHAPE1B ON build_niagara.py 1
VFXPORT_MESHVCOL ON u1e_build.py 1
VFXPORT_MIRROR ON build_niagara.py 1
VFXPORT_NEVERFIRES_M ON build_niagara.py 1
VFXPORT_NODESHEAR ON build_niagara.py, vm1_author.py 2
VFXPORT_NODESHEAR2 ON build_niagara.py, vm1_author.py 2
VFXPORT_NODESHEAR_BILL ON build_niagara.py 1
VFXPORT_NODESHEAR_BILL3D ON build_niagara.py 1
VFXPORT_PREWARM_STATIONARY ON build_niagara.py 1
VFXPORT_RAMPHI ON vm1_hlsl2.py 1
VFXPORT_RATECURVE ON build_niagara.py 1
VFXPORT_RECTSPEED ON build_niagara.py 1
VFXPORT_RINGBUF ON build_niagara.py 1
VFXPORT_RINGLOOP ON build_niagara.py 1
VFXPORT_RPROT ON build_niagara.py 1
VFXPORT_SHAPESCALE ON build_niagara.py 1
VFXPORT_SHAPESCALE2 ON build_niagara.py 1
VFXPORT_SHAPESCALE2B ON build_niagara.py 1
VFXPORT_SIBPLAN ON build_niagara.py 1
VFXPORT_SPAWNSCALE ON build_niagara.py 1
VFXPORT_SPAWNSCALE_W ON build_niagara.py 1
VFXPORT_SPEEDCURVE ON build_niagara.py 1
VFXPORT_SPOSUNIT ON build_niagara.py 1
VFXPORT_STARTCURVE ON build_niagara.py 1
VFXPORT_STEPCHAIN ON build_niagara.py 1
VFXPORT_STREAM2 ON build_niagara.py 1
VFXPORT_STRETCHSHEAR ON shuriken_size.py, vm1_author.py 2
VFXPORT_SUBABSENT ON build_niagara.py 1
VFXPORT_SUBCHAIN ON build_niagara.py 1
VFXPORT_SUBINHERIT_ROT ON build_niagara.py 1
VFXPORT_SUBSHAPEPOS OFF - deliberately, not verified yet build_niagara.py 1
VFXPORT_SUBWINDOW ON build_niagara.py 1
VFXPORT_TEXMIPS ON vm1_author.py 1
VFXPORT_TRAILFIRED ON build_niagara.py 1
VFXPORT_TRAILSCALE ON build_niagara.py 1
VFXPORT_TRAILSPAWN ON build_niagara.py 1
VFXPORT_TRAILSUB ON build_niagara.py 1
VFXPORT_URPLIT ON u1e_urplit.py 1
VFXPORT_UVSLOT ON build_niagara.py, vm1_author.py 2
VFXPORT_VBANY ON shuriken_size.py 1
VFXPORT_VIEWSHEAR ON shuriken_size.py, vm1_author.py 2
VFXPORT_VMESH ON build_niagara.py 1
VFXPORT_VMESHNU ON build_niagara.py 1
VFXPORT_VMESHS ON build_niagara.py 1
VFXPORT_VR3D ON build_niagara.py 1
VFXPORT_WARMBURST ON build_niagara.py 1
VFXPORT_WSCALE ON build_niagara.py 1
VFXPORT_WSTRETCH ON build_niagara.py 1

Tools (generated)

733 tool files inventoried in the toolkit's working trees (u2ue/survey/pt1_inventory.json), 236 of them in the package; 143 are the core chain a port runs (pt1_core.json). The rest are the reference port's own steps, gates and one-off probes, which u2ue release leaves out (its manifest, u2ue/release.py, names what ships and why). Every file's one-line purpose, usage, selftest and bindings are rows of the inventory itself.

where tools in the package in the core chain with a selftest
scenes_tools 211 33 24 14
effects_tools 194 102 86 68
effects_lane 141 31 10 7
unity_probe 103 33 11 30
model_gates 24 8 0 16
vfxport 23 18 12 12
ui_tools 12 11 0 0
units_tools 12 0 0 0
session_queues 10 0 2 1
tiles_tools 2 0 0 0
hud_tools 1 0 0 0

Selftests (generated)

107 selftests run by py -m u2ue --project <name> check --only selftests, each its tool's own:

selftest command
shuriken_size.py shuriken_size.py
subframe_rule.py subframe_rule.py --selftest
cube_remap.py cube_remap.py --selftest
niagara_names.py niagara_names.py
whole_trace.py whole_trace.py --selftest
burst_trace.py burst_trace.py --selftest
sub_frame_rule_check.py sub_frame_rule_check.py --plants
shape_scale_judge.py shape_scale_judge.py --selftest
nodeshear2_rule_check.py ns2_selftest.py
trailscale_check.py trailscale_selftest.py
ringbuffer_check.py ringbuffer_check.py --selftest
nonuniform_motion_judge.py nonuniform_motion_judge.py --selftest
nonuniform_world_judge.py nonuniform_world_judge.py --selftest
u1e_preflight.py u1e_preflight.py --selftest
u1e_exr.py u1e_exr.py --selftest
u1e_burstp_judge.py u1e_burstp_judge.py --selftest
u1e_simulates_check.py u1e_simulates_check.py --selftest
u1e_slots.py u1e_slots.py --selftest
u1e_gamerules.py u1e_gamerules.py
u1e_names_gate.py u1e_names_gate.py --selftest
u1e_nested.py u1e_nested.py
u1e_material_errors.py u1e_material_errors.py --selftest
u1e_never_fires.py u1e_never_fires.py --selftest
u1e_objmesh.py u1e_objmesh.py --selftest
u1e_unitymesh.py u1e_unitymesh.py --selftest
u1e_blends.py u1e_blends.py --selftest
vm1_read_materials.py vm1_read_materials.py --selftest
u1e_psd.py u1e_psd.py --selftest
u1e_missing_assets.py u1e_missing_assets.py --selftest
vm1_account.py vm1_account.py --selftest
fx17_checks.py fx17_checks.py --selftest
v4_msg_gate.py v4_msg_gate.py --selftest
u1e_fx37v_check.py u1e_fx37v_check.py --selftest
converter_trace_gate.py converter_trace_gate.py --selftest
unreachable_gate.py unreachable_gate.py --selftest
v4_write_gate.py v4_write_gate.py --selftest
v4_module_inputs.py v4_module_inputs.py --selftest
host_gate.py host_gate.py --selftest
scene_fidelity_gate.py (a synthetic scene of its own) scene_fidelity_gate.py --selftest
layer_gate.py layer_gate.py --selftest
logic_diff.py logic_diff.py --selftest
tempo.py -m u2ue.verbs.tempo --selftest
adapters -m u2ue.adapters
find -m u2ue find --selftest
usecase_absence.py usecase_absence.py --selftest
uml.py uml.py selftest
trailrend_judge.py trailrend_judge.py --selftest
timeline_judge.py timeline_judge.py --selftest
trailrend2_judge.py trailrend2_judge.py --selftest
trailrend3_judge.py trailrend3_judge.py --selftest
inventory -m u2ue.verbs.inventory --selftest
data -m u2ue.verbs.data --selftest
transform -m u2ue.transform
shear -m u2ue.verbs.shear --selftest
parity -m u2ue.verbs.parity --selftest
ui -m u2ue.verbs.ui --selftest
scene (the verb's refusals) -m u2ue.verbs.scene --selftest
manual build (the naming gate) u2ue/manual/build.py --selftest
u1e_fixed_plane_check.py u1e_fixed_plane_check.py --selftest
x2_draws.py x2_draws.py --selftest
u1e_reuse_selftest.py u1e_reuse_selftest.py
u2ue (a verb's help runs nothing) -m u2ue --selftest
u2ue cycle -m u2ue.verbs.cycle --selftest
concepts_gate.py concepts_gate.py --selftest
u2ue scaffold -m u2ue.verbs.scaffold --selftest
u2ue logic -m u2ue.verbs.logic --selftest
skill_gate.py skill_gate.py --selftest
req_harvest.py req_harvest.py --selftest
usecase_gaps.py usecase_gaps.py --selftest
showcase.py showcase.py --selftest
p2_land.py p2_land.py --selftest
patch_reach.py patch_reach.py --selftest
u2ue digest -m u2ue.verbs.digest --selftest
hardwired.py hardwired.py --selftest
probe_spawn_gate.py probe_spawn_gate.py --selftest
yaml_field_gate.py yaml_field_gate.py --selftest
u2ue window -m u2ue.verbs.window --selftest
u2ue editorlink -m u2ue.editorlink --selftest
u2ue trial -m u2ue.verbs.trial --selftest
console_check.py console_check.py --selftest
headless_nunit.py headless_nunit.py --selftest
bee_dag.py bee_dag.py --selftest
rule_probes.py rule_probes.py --selftest
u2ue conform -m u2ue.verbs.conform --selftest
u2ue readback -m u2ue.readback --selftest
u2ue probecase -m u2ue.probecase --selftest
u2ue judge -m u2ue.judge --selftest
simspeed_rule.py simspeed_rule.py --selftest
u2ue capture -m u2ue.capture --selftest
u2ue acceptance -m u2ue.acceptance --selftest
u2ue photo -m u2ue.verbs.photo --selftest
u2ue seam -m u2ue.seam --selftest
u2ue assetfamily -m u2ue.assetfamily --selftest
u2ue host -m u2ue.verbs.host --selftest
u2ue run -m u2ue.run --selftest
tool (verb) -c import sys; from u2ue.verbs import tool; sys.exit(tool.selftest())
u2ue release -m u2ue.verbs.release --selftest
u2ue uml -m u2ue.verbs.uml --selftest
u2ue project -m u2ue.project --selftest
u2ue slice -m u2ue.verbs.slice --selftest
u2ue cite -m u2ue.verbs.cite --selftest
u2ue req -m u2ue.verbs.req --selftest
u2ue mutate -m u2ue.verbs.mutate --selftest
u2ue port -m u2ue.verbs.port --selftest
u2ue estimate -m u2ue.verbs.estimate --selftest
token_basis.py token_basis.py --selftest
u2ue blueprint -m u2ue.verbs.blueprint --selftest
  • plugin_sync_gate.py is NOT run by u2ue check: its selftest corrupts and then restores the plugin DLL an open Unity editor loads - a reload nobody asked for, so it is run by hand with the editor closed

A game's own gates (the ones written against its model, its adapter or its HUD) are rows in ITS project file, under selftests: runs (each {"tool", "in": a toolkit part or "home", "sub", "argv"}) and not_run ({tool: the measured reason}). The check runs them after the rows above.

22. Architecture and the UML

Who this is for: the reviewer checking how u2ue ports, and the toolkit developer changing its structure - the layers, every generated diagram, the review's findings and the use case model behind them.

This chapter is the map. The long form is the toolkit's own u2ue/ARCHITECTURE.md: the pipeline, the principles, the converter, the design read from the code, the review with each proof, and the questions a senior engineer will ask, with their answers.

Layers

flowchart TB
  F["Facade: py -m u2ue - one verb registry"]
  F --> P["Project file - where this game's files are"]
  F --> A["Adapter - this game's own rules (3 questions)"]
  F --> K["Shared knowledge - transform, facts, routes, tools"]
  F --> T["Tools - readers, converter, Unreal steps, gates, report"]
  K --> T
  A --> T
  M["The game's engine-free model"] --> RT["Runtime library (.NET) - Unity's runtime rules"]
  • The facade is the single entry point. Every verb is one row of one registry, which the command line, the verb list, find and this manual all read.
  • The project file holds every path and choice that differs between games; the adapter holds what differs between games' rules (three questions, Chapter 18). The core knows no game: adapters are discovered by name.
  • Shared knowledge is held once: the transform conventions (u2ue.transform), the measured rules and the Unity version each was measured on (facts), the converter's switches and their evidence (routes), and where each part of the toolkit lives (tools).
  • Tools stay runnable alone and keep their own selftests. A verb runs a tool as a subprocess with the project's environment; it never re-implements one.
  • The runtime library (u2ue/runtime/U2ue.Runtime, plain .NET) is what the game's engine-free model references (Chapter 5). It and the host templates (u2ue/templates/unreal, copied into the game's own Unreal project, Chapter 13) are the parts that ship into a game.

Principles

The review's yardstick is Chapter 1's three principles, each enforced rather than recommended: read or absent, never a guess (Chapter 9 has the gates); every rule measured in Unity by a probe and a judge written before the bake (Chapter 8); every change proven before it ships, behind a switch, replayed by whole_trace.py over every emitter, trialled, then flipped (Chapter 7).

The UML in this manual

Every UML view in this manual is GENERATED (from the code, from the requirements model, or for the concept model from u2ue/CONCEPTS.md) and checked on every build, so a view that names a class, a verb or a step the toolkit does not have cannot be published. The layer sketch above is drawn by hand, as are the few flowcharts in Parts I and II: sketches, not generated views. Read the generated views in this order:

  1. The concept model (below): the ideas a person needs to follow a port, each one class. It was drawn before the code, and a gate checks that every concept it calls a class exists at its own line.
  2. The use case model (Chapter 17): who uses the toolkit for what - the use case diagram, the epic's activity flow, every case fully dressed with the document each step was read from.
  3. The facade's requirements (Chapter 19): every verb as a requirement, read from its own source - its inputs, its refusals with their lines, its exits, the selftest that verifies it and the use-case steps that run it.
  4. The class model (below): the toolkit's modules and classes and how they use one another, from the code's imports and bases.
  5. The facade map (below): which modules and tool parts each verb reaches.
  6. The traceability (Appendix E): each stakeholder requirement down to the selftest that proves it.

A reviewer starts at the epic (Chapter 17), follows a step into the verb that proves it (Chapter 19), and only then opens code.

The concept model

classDiagram
    direction LR
    class Project {
        the game being ported: its paths, its Adapter
        env()  get()
    }
    class Adapter {
        the game's answers to the few game-specific questions
        effect_keys()  spawn_rules  host_busy()
    }
    class AssetFamily {
        one kind of asset that ports itself
        extract()  build()  read()  judge()  photo()
    }
    class Route {
        one Unity behaviour -> its Unreal form, behind a switch
        switch  files  evidence  state: ON|OFF|DELIBERATELY OFF
    }
    class Rule {
        a measured fact about Unity, per Unity version
        file  unity_version  held_to  verified_for(version)
    }
    class ProbeCase {
        one controlled Unity measurement (data, not a new .cs)
        prefab()  synthetic()  as_dict()
    }
    class CaseRun {
        a named set of ProbeCases and the window that reads them
        write()  window_spec()
    }
    class Window {
        an idle-safe Unity run of ProbeCases
    }
    class EditorLink {
        how the toolkit talks to a Unity editor: one contract, two ways in
        status()  recompile()  play()  stop()  run_menu()  console()
    }
    class Capture {
        a deterministic frame of one side (seed, clock, step pinned)
    }
    class Readback {
        what a built asset actually computes, per frame
        collect()  summary()  missing()  record()
    }
    class Judge {
        compares a Readback or Capture with a Rule or with Unity
        plant()  "must fail on its plant"
    }
    class Trial {
        a Route tried on real keys in its own content root (data), or a delta rebuilt into the content root itself
    }
    class Acceptance {
        which build made each key's system in the content root: the record the acceptance page reads for it
        take(record, label)  overrides()
    }
    class Run {
        one pinned, stoppable job: the code it runs is a snapshot, never the live tree
        pin(parts) env  snapshot  commits  stop()  record()
    }
    class Pillar {
        one promise of the product
    }
    class Check {
        one recurring check of a Pillar
        commit  "fast enough for every commit"
    }
    class CommitGate {
        the commit-marked checks, on every commit staging a toolkit file
        touched()  checks()  run()
    }
    class LogicPort {
        the skill: a game's C# -> an engine-free Core + seams
    }
    class Seam {
        an interface the engine implements (platform / view / capability)
    }
    class Gate {
        a rule the ported logic must hold (layer, host, parity, publish)
    }
    class ReaderReads {
        every field the IR reader reads, keyed by its module path (ColorModule.gradient), read off the reader's source
        of(source)  reads(module, key)  leaks()
    }
    class SliceLanding {
        a slice written into the live project only in the owner's absence, then played
        cut()  land()  restore()
    }
    class SliceStep {
        an editor step a slice declares: a menu run after its compile, the files it writes
        load()  menu  writes  because
    }
    class Citation {
        a File.cs:N breadcrumb in the model's comments, held to the code it names
        cited()  pattern()
    }
    class SliceGate {
        every check one refactor slice must pass before it lands
        steps()  run()  record()
    }
    class ByNameReach {
        a member a slice turned from a field into a property, or a type it deleted, still reached by NAME
        declared()  converted()  deleted()  retyped()  findings()
    }
    class TextAnchorReach {
        a test that reads a script's TEXT by path, for a literal the slice moved out of it
        findings()
    }
    class StandingCompileErrors {
        a compile error the live project has too, against the model's source - another writer's, named
        key()  split()  unproven()
    }
    class LandingProof {
        the tests only a landing can prove, judged on the model the engine loaded
        model_dir()  recordings()  replayed()  write_replayed()  run()
    }
    class SliceBlobs {
        the file versions a stacked slice was cut on, by hash: the merge base for a lower slice's late fix
        keep()  find()
    }
    class LineEndingKeep {
        an overlay keeps every live file's CRLF / LF style: a flip is every line changed for version control
        flips()
    }
    class SharedScripts {
        a Unity script a headless project ALSO compiles: built and tested again as the slice leaves it
        compiled()  carried()  props()  unseen()
    }
    class EditorAutoRuns {
        the editor's own suites a landing RUNS and waits for, read from the editor's log, never its Console window
        refusal()  menus()  unreported()
    }
    class PresentationTrace {
        what a seeded battle SHOWED, in order, read from the editor's log: compared like its events
        refusal()  trace()  write()
    }
    class Release {
        the package as a repo: a manifest of what ships, assembled, never hand-copied
        assemble()  check()  readiness()
    }
    class ToolkitHistory {
        what the toolkit keeps in its own repository and never ships: its instruments over the reference port and their history
        kept(path)  readers(files)
    }
    class ShippedClosure {
        what a release ships of the toolkit's parts: what the facade reaches, by import, by name in its code, by build item
        seeds()  edges(path)  reached()
    }
    class ReleaseProof {
        a release proven where a customer holds it: assembled fresh, a git checkout of itself, a second game's selftests run inside
        assemble()  clone()  check()
    }
    class SelftestRegistry {
        every tool's own offline selftest as a row; a release reports the rows whose tool it kept out, never runs them
        runs(project)  kept_out(rows, release)
    }
    class RequirementCheck {
        every // REQ: citation in the game's code, resolved in the requirement documents its project file names
        from_project(p)  citations(path, text)  resolve(c)  run(paths)
    }
    class RequirementSource {
        one requirement document or folder of them, cited by line or id, by section, or by entry name
        begins(text)  resolve(doc, rest)  entries()
    }
    class MutationRun {
        a file of mutations tried one at a time on a fresh copy of what the project declares: would any test notice
        from_project(p, spec_path)  sources()  make_copy()  run_tests(filt)  run(keep)
    }
    class Mutation {
        one deliberate change to a rule the tests must notice: its file, its anchor, its new text, the claim it tests
        apply(text)
    }
    class StorePackage {
        the Unity half as an Asset Store package, held to the store's rules: each a count
        files()  metas()  documentation()  checks()  compile()  package_json()  assemble()  assemble_classic()
    }
    class StoreLayout {
        where the store package's files go: a Package Manager package, or a classic one folder under Assets
        doc_dir()  sample_path(sample)
    }
    class PackageCompile {
        the store package's C# compiled alone, against Unity's own assemblies only
        version()  command()  run()
    }
    class HostProject {
        the game's own Unreal project, made as a customer makes one
        steps()  create()  install()  wire()  judge()
    }
    class PortPlan {
        a whole port as ordered Stages, one command
        stages()  next(state)
    }
    class Stage {
        one step of a port: AUTOMATIC | EDITOR | AI | OWNER
        command  done(project)  question
    }
    class PortRun {
        the plan run in order: stop on red, resume, ask at a person's or the AI's step
        run()  record()
    }
    class Census {
        what a Unity project holds to port, READ off its files
        code lines pure | coupled  scenes  prefabs  screens
    }
    class MvcCensus {
        every MonoBehaviour's state, member by member, and the model's members of its name
        run()  kind()  model_index()
    }
    class TokenUse {
        one model call's tokens: input, cache writes, cache reads, output
        cost(prices)  uncached_cost(prices)
    }
    class MeasuredRate {
        tokens per unit, read from records: n, spread, provenance - or ABSENT
        band()  provenance
    }
    class PriceTable {
        a model's prices per token kind, READ from the vendor's page with its date
    }
    class Estimate {
        a Census times MeasuredRates: tokens, cache split, cost, confidence, saving
        stages()  total()  saving()
    }
    Project --> Adapter : asks
    Project --> AssetFamily : ports with
    AssetFamily --> Route : converts by
    Route --> Rule : follows
    Rule --> ProbeCase : measured by
    ProbeCase --> Window : runs in
    Window --> EditorLink : asks the editor through (a game's own bridge, or the package's channel)
    StorePackage --> EditorLink : ships the editor's side of (EditorChannel)
    Route --> Trial : tried by
    Trial --> Run : is a
    Trial --> Readback : reads
    Trial --> Capture : photographs
    Trial --> Acceptance : a build into the content root is taken by
    Judge --> Readback : reads
    Judge --> Capture : reads
    Judge --> Rule : holds to
    Pillar --> Check : held by
    CommitGate --> Check : runs the commit-marked
    Project --> LogicPort : ports logic with
    LogicPort --> Seam : cuts
    LogicPort --> Gate : passes
    SliceGate --> Gate : runs, in order
    SliceGate --> ByNameReach : checks the overlay with
    SliceGate --> TextAnchorReach : checks the overlay with
    SliceGate --> StandingCompileErrors : tells the slice's compile errors from the live project's with
    SliceGate --> LineEndingKeep : checks the overlay with
    SliceGate --> SharedScripts : builds and tests the overlay's shared scripts with
    SliceLanding --> SliceGate : lands only after it passes
    SliceLanding --> LandingProof : proves the editor's recording with
    SliceLanding --> SliceBlobs : rebases a stacked slice on, three ways
    SliceLanding --> EditorAutoRuns : runs, then reads the summaries of
    SliceLanding --> PresentationTrace : compares what each battle showed with
    SliceLanding --> SliceStep : runs, after the compile and before the proofs, the declared
    SliceGate --> LandingProof : names PENDING from
    LogicPort --> HostProject : runs the Core on
    HostProject --> Gate : proven by (parity)
    Gate --> ReaderReads : credits a Unity field only on the module it is read from (the field gate)
    Release --> Pillar : delivers (8, packaging)
    Release --> ToolkitHistory : keeps out, and refuses a shipped file that reads, what
    Release --> ShippedClosure : ships of each part only what the facade reaches, by
    ReleaseProof --> Release : proves, inside a checkout of it, on a second game
    SelftestRegistry --> Release : leaves out the rows of the tools kept out of
    Project --> RequirementCheck : holds the game's code to its requirement documents with (u2ue req)
    RequirementCheck --> RequirementSource : resolves each citation in
    Project --> MutationRun : asks whether any test notices a changed rule with (u2ue mutate)
    MutationRun --> Mutation : tries, one at a time, on a fresh copy
    StorePackage --> Release : the store's half of, named by the same naming rule
    StorePackage --> PackageCompile : proven to build alone by (rule 1.1.b)
    StorePackage --> StoreSample : ships under Samples~ (rule 1.1.f)
    StorePackage --> StoreLayout : lays its files out by (UPM or CLASSIC)
    SliceGate --> Citation : the model's breadcrumbs, held to the code a slice moves (u2ue cite)
    Project --> PortPlan : ported by
    PortPlan --> Stage : orders
    PortRun --> PortPlan : runs
    Stage --> LogicPort : the AI stage is
    LogicPort --> MvcCensus : sorts each MonoBehaviour by (u2ue-mvc step 1)
    Estimate --> Census : counts
    Estimate --> MeasuredRate : multiplies by
    Estimate --> PriceTable : prices with
    MeasuredRate --> TokenUse : measured from

The target model, from u2ue/CONCEPTS.md. u2ue/survey/concepts_gate.py checks every concept the table there says is a class against the code: 57 of 57 exist as classes today, each at its own line (exit 0).

The class model

Every module and class of the toolkit (a game's adapter apart), and what each one uses. The next section reads it as layers.

name kind members uses
_Engines class 2 -
_Fake class 3 -
_FakeEditor class 24 extends EditorWorld
_ObjectStream class 5 -
_P class 2 -
_SimEditor class 4 -
Absent class 2 extends Check
Acceptance class 4 -
acceptance module 1 -
AcceptanceError class 0 -
adapters module 5 keys
AssetFamily class 4 -
assetfamily module 4 verbs
Bridge class 2 -
ByNameReach class 15 -
Capture class 6 -
capture module 1 -
CaptureError class 0 -
CaseRun class 4 -
catalog module 11 adapters, routes, tools, verbs
Census class 9 -
ChannelLink class 13 extends EditorLink
Check class 3 -
Citation class 3 -
CitationCheck class 5 -
cli module 1 project, verbs
CommitGate class 4 -
Ctx class 2 -
DigestError class 0 -
EditorAutoRuns class 7 -
EditorLink class 9 -
editorlink module 18 -
EditorWorld class 23 -
Entry class 1 -
env module 1 tools
Estimate class 5 -
estimate module 2 verbs_inventory
Exec class 6 -
Facade class 2 -
facts module 2 tools
Fake class 5 -
FakeExec class 7 extends Exec
FakeFacade class 1 -
FakeWorld class 16 extends World
FixtureProject class 2 -
Gate class 4 -
gates module 2 tools
Held class 2 extends Check
HostError class 0 -
HostProject class 20 -
hostproject module 3 -
HttpLink class 10 extends EditorLink
InRaw class 0 -
Judge class 6 -
judge module 2 tools
keys module 3 -
LandingProof class 9 -
LineEndingKeep class 3 -
logic module 1 seam
LogicPort class 17 -
MeasuredRate class 9 -
Mutation class 2 -
mutation module 3 -
MutationError class 0 -
MutationRun class 6 -
MvcCensus class 7 -
P class 2 -
PackageCompile class 8 -
Pillar class 2 -
pillars module 2 project, tools
PlanExec class 4 extends Exec
port module 16 logic, verbs__ue
PortPlan class 3 -
PortRun class 4 -
Prerequisite class 2 -
PresentationTrace class 6 -
PriceTable class 3 -
ProbeCase class 4 -
probecase module 1 -
Proj class 2 -
Project class 6 -
project module 1 tools
ProjectError class 0 -
Q class 0 -
Reached class 0 -
Readback class 7 -
readback module 1 -
ReadbackError class 0 -
RealEditorWorld class 24 extends EditorWorld
RealExec class 7 extends Exec
RealWorld class 13 extends World
Refused class 0 -
Release class 18 -
release module 3 facts, selftests, tools
ReleaseProof class 6 -
ReqCitation class 3 -
RequirementCheck class 6 -
RequirementError class 0 -
requirements module 4 -
RequirementSource class 8 -
Result class 2 -
Route class 4 -
routes module 5 tools
Rule class 4 -
Run class 10 -
run module 2 tools
RunError class 0 -
Seam class 4 -
seam module 6 project
SelftestRegistry class 3 -
selftests module 4 project, tools
SharedScripts class 7 -
Ship class 3 -
ShippedClosure class 8 -
slice module 10 editorlink, gates, tools
SliceBlobs class 4 -
SliceError class 0 -
SliceGate class 18 -
SliceLanding class 25 -
SliceStep class 2 -
Stage class 2 -
StandingCompileErrors class 5 -
Step class 3 -
Stop class 0 -
StoreEntry class 1 -
StoreLayout class 3 -
StorePackage class 18 -
StoreSample class 3 -
templates_unreal_Plugins_U2ueAudio_selftest_judge module 8 -
TextAnchorReach class 10 -
TokenUse class 11 -
ToolError class 0 -
ToolkitHistory class 4 -
tools module 9 -
TraceIncomplete class 0 extends SliceError
transform module 19 tools
Trend class 2 extends Check
Trial class 18 -
UnityProject class 2 -
verbs module 6 tools; runs: verbs_blueprint, verbs_build, verbs_check, verbs_cite, verbs_conform, verbs_cycle, verbs_data, verbs_digest, verbs_estimate, verbs_extract, verbs_find, verbs_host, verbs_info, verbs_inventory, verbs_judge, verbs_logic, verbs_metrics, verbs_mutate, verbs_parity, verbs_photo, verbs_port, verbs_read, verbs_release, verbs_report, verbs_req, verbs_scaffold, verbs_scene, verbs_shear, verbs_slice, verbs_tempo, verbs_tool, verbs_trial, verbs_ui, verbs_uml, verbs_window
Window class 17 -
World class 13 -
verbs__ue module 7 adapters, hostproject, tools
verbs_blueprint module 15 tools
verbs_build module 2 verbs__ue
verbs_check module 6 facts, gates, selftests, tools
verbs_cite module 3 Citation, CitationCheck
verbs_conform module 29 probecase, readback, tools
verbs_cycle module 7 pillars, tools
verbs_data module 7 tools
verbs_digest module 17 facts, project
verbs_estimate module 4 estimate
verbs_extract module 4 adapters, tools
verbs_find module 2 catalog
verbs_host module 6 hostproject, project, tools, verbs__ue
verbs_info module 1 adapters
verbs_inventory module 19 -
verbs_judge module 1 judge
verbs_logic module 2 logic
verbs_metrics module 3 facts, routes, tools
verbs_mutate module 2 mutation
verbs_parity module 2 tools
verbs_photo module 3 capture, keys, verbs__ue
verbs_port module 3 port, verbs
verbs_read module 1 readback, verbs__ue
verbs_release module 14 release, selftests, tools
verbs_report module 1 tools
verbs_req module 2 requirements
verbs_scaffold module 7 gates, project
verbs_scene module 4 project, tools, verbs__ue
verbs_shear module 6 tools, transform
verbs_slice module 18 editorlink, slice, tools
verbs_tempo module 6 routes
verbs_tool module 4 tools
verbs_trial module 8 acceptance, capture, readback, run, tools
verbs_ui module 4 tools
verbs_uml module 5 project
verbs_window module 11 editorlink, tools

2 game adapter module(s) and class(es) left out: an adapter is its game's code (Chapter 18). drew 192 classes / modules, 151 relationships (members: uml.py extract; edges: the code's own imports and bases), generated by u2ue/survey/design_diagram.py; run py u2ue/survey/design_diagram.py OUT.mmd for the diagram, which lists up to 12 members per class with their signatures (--members N for more).

The facade's layers, read from the code

To see the class model as a diagram, run py u2ue/survey/design_diagram.py OUT.mmd --members 0 (members come from uml.py's extraction, edges from the code's own imports and class bases). --members 0 lists no members; without it each class lists its first 12 with their real signatures and counts the rest. In that diagram a dashed arrow is "imports", "runs" marks a row of the verb registry, and a hollow triangle is a base class. Read top to bottom, the facade has five layers:

  • cli (u2ue/__main__.py) - the only entry. It reads --project and asks the registry; it knows no verb by name but info, the default.
  • verbs (u2ue/verbs/__init__.py, VERBS) - one row per verb: its name, whether it needs a project and what it does; its module is u2ue/verbs/<name>.py. Dispatch, the usage text of py -m u2ue and the verb source of find all read this one table.
  • the verb modules - each a run(p, argv). No verb imports another verb: an edge inside verbs goes to _ue, the private helper the verbs that launch Unreal share (build, read, photo, host, scene), and what two verbs share lives one layer down: check and scaffold both judge a model by gates.model_failures. That move removed the last exception, verbs_scaffold using verbs_check.
  • the shared services - among them Project (one game's paths), tools (part(): every toolkit directory named once), adapters (the ports), catalog (what find searches), routes (the flip table), facts (which Unity measured each rule), keys.
  • the tools - the converter, the readers, the judges. The verbs RUN them as processes, so each still runs by hand with its own selftest; the facade loads a tool's file only to read a table it holds (routes: the flip table and the deliberately-OFF list; check: the selftest list), and u2ue.transform's selftest loads the converter to cross-check its arithmetic.

The facade map

Each verb is a thin module: it reads the project, calls the shared modules it imports, and runs any tools as subprocesses with the project's environment. The map shows which shared modules each verb imports and which tool parts it runs tools from.

flowchart LR
    subgraph V["the facade: py -m u2ue &lt;verb&gt;"]
        v_find["find"]
        v_estimate["estimate"]
        v_port["port"]
        v_info["info"]
        v_inventory["inventory"]
        v_uml["uml"]
        v_scaffold["scaffold"]
        v_slice["slice"]
        v_cite["cite"]
        v_mutate["mutate"]
        v_req["req"]
        v_logic["logic"]
        v_data["data"]
        v_shear["shear"]
        v_scene["scene"]
        v_parity["parity"]
        v_digest["digest"]
        v_host["host"]
        v_ui["ui"]
        v_window["window"]
        v_trial["trial"]
        v_conform["conform"]
        v_judge["judge"]
        v_extract["extract"]
        v_check["check"]
        v_build["build"]
        v_read["read"]
        v_photo["photo"]
        v_report["report"]
        v_metrics["metrics"]
        v_tempo["tempo"]
        v_cycle["cycle"]
        v_tool["tool"]
        v_release["release"]
        v_blueprint["blueprint"]
    end
    subgraph M["the toolkit's modules (u2ue/)"]
        m_acceptance["acceptance"]
        m_adapters["adapters"]
        m_capture["capture"]
        m_catalog["catalog"]
        m_citation["citation"]
        m_editorlink["editorlink"]
        m_estimate["estimate"]
        m_facts["facts"]
        m_hostproject["hostproject"]
        m_judge["judge"]
        m_keys["keys"]
        m_logic["logic"]
        m_mutation["mutation"]
        m_port["port"]
        m_probecase["probecase"]
        m_project["project"]
        m_readback["readback"]
        m_release["release"]
        m_requirements["requirements"]
        m_routes["routes"]
        m_run["run"]
        m_selftests["selftests"]
        m_slice["slice"]
        m_tools["tools"]
        m_transform["transform"]
        m_verbsNAMES["verbs.NAMES"]
        m_verbs_ue["verbs._ue"]
    end
    subgraph P["the tool parts (u2ue/tools.py PARTS)"]
        p_blueprint[("blueprint")]
        p_conformance[("conformance")]
        p_effects_tools[("effects_tools")]
        p_lane[("lane")]
        p_scene_tools[("scene_tools")]
        p_ui[("ui")]
        p_vfxport[("vfxport")]
    end
    v_find --> m_catalog
    v_estimate --> m_estimate
    v_port --> m_port
    v_port --> m_verbsNAMES
    v_info --> m_adapters
    v_uml --> m_project
    v_scaffold --> m_project
    v_slice --> m_editorlink
    v_slice --> m_slice
    v_slice --> m_tools
    v_slice -.-> p_lane
    v_cite --> m_citation
    v_mutate --> m_mutation
    v_req --> m_requirements
    v_logic --> m_logic
    v_data --> m_tools
    v_data -.-> p_effects_tools
    v_data -.-> p_vfxport
    v_shear --> m_tools
    v_shear --> m_transform
    v_scene --> m_project
    v_scene --> m_tools
    v_scene --> m_verbs_ue
    v_scene -.-> p_scene_tools
    v_parity --> m_tools
    v_digest --> m_facts
    v_digest --> m_project
    v_host --> m_hostproject
    v_host --> m_project
    v_host --> m_tools
    v_host --> m_verbs_ue
    v_host -.-> p_scene_tools
    v_ui --> m_tools
    v_ui -.-> p_ui
    v_window --> m_editorlink
    v_window --> m_tools
    v_window -.-> p_conformance
    v_window -.-> p_lane
    v_trial --> m_acceptance
    v_trial --> m_capture
    v_trial --> m_readback
    v_trial --> m_run
    v_trial --> m_tools
    v_conform --> m_probecase
    v_conform --> m_readback
    v_conform --> m_tools
    v_conform -.-> p_conformance
    v_conform -.-> p_lane
    v_conform -.-> p_vfxport
    v_judge --> m_judge
    v_extract --> m_adapters
    v_extract --> m_tools
    v_check --> m_facts
    v_check --> m_selftests
    v_check --> m_tools
    v_check -.-> p_vfxport
    v_build --> m_verbs_ue
    v_read --> m_readback
    v_read --> m_verbs_ue
    v_photo --> m_capture
    v_photo --> m_keys
    v_photo --> m_verbs_ue
    v_report --> m_tools
    v_metrics --> m_facts
    v_metrics --> m_routes
    v_metrics --> m_tools
    v_metrics -.-> p_effects_tools
    v_tempo --> m_routes
    v_cycle --> m_tools
    v_tool --> m_tools
    v_release --> m_release
    v_release --> m_selftests
    v_release --> m_tools
    v_blueprint --> m_tools
    v_blueprint -.-> p_blueprint
verb imports runs tools in
find catalog -
estimate estimate -
port port, verbs.NAMES -
info adapters -
inventory - -
uml project -
scaffold project -
slice editorlink, slice, tools lane
cite citation -
mutate mutation -
req requirements -
logic logic -
data tools effects_tools, vfxport
shear tools, transform -
scene project, tools, verbs._ue scene_tools
parity tools -
digest facts, project -
host hostproject, project, tools, verbs._ue scene_tools
ui tools ui
window editorlink, tools conformance, lane
trial acceptance, capture, readback, run, tools -
conform probecase, readback, tools conformance, lane, vfxport
judge judge -
extract adapters, tools -
check facts, selftests, tools vfxport
build verbs._ue -
read readback, verbs._ue -
photo capture, keys, verbs._ue -
report tools -
metrics facts, routes, tools effects_tools
tempo routes -
cycle tools -
tool tools -
release release, selftests, tools -
blueprint tools blueprint

35 verbs, 27 modules, 7 tool parts; a solid arrow is an import, a dashed one a tool the verb runs from that part. Generated from each verb module's imports and its part() calls.

The review, finding by finding

The class model was reviewed on 2026-10-15 against one question: is the way the toolkit ports logical, efficient and as simple as possible to grasp? Each finding names its module. A refactor counted as done only when the outputs it touched were proven unchanged (the full review, with each proof: u2ue/ARCHITECTURE.md, "The review"). A developer extending the toolkit keeps to what the DONE rows established: no verb imports a verb, no literal tool path in the facade, one registry, and a core that knows no game.

# where what was wrong what is better status, and the proof
1 adapters and the reference port's adapter a CYCLE: the ports imported one game's adapter adapters discovered by name (a module that declares ADAPTER); the core knows no game DONE: outputs byte-identical; the old queue guard, planted, fails the adapter's selftest
2 verbs.metrics -> verbs.check, verbs.tempo a verb imported verbs for shared logic that logic moved into facts and routes DONE: metrics, tempo, info and check --only facts byte-identical
3 verbs._ue the effect tools named by a literal path tools.part("effects_tools") DONE
4 cli an if/elif chain of verbs, with the usage text kept separately one registry that dispatch, the usage and find read DONE: every verb dispatches as before
5 build_niagara.build_emitter one 1,430-line function with 221 locals twenty stages in Unity's module order, the state handed on one object (_EmitterBuild) DONE: whole_trace.py shows 0 calls differ, 0 exceptions
6 uml.py, the reviewer's own instrument every package __init__ merged into one type; check blind to Python; nested functions drawn as members each fixed, each with a selftest case that fails on the old behaviour DONE
7 the flip switches the switches now permanently ON still carry OFF branches that are dead code retire them in one pass that whole_trace.py proves OPEN (Appendix B)
8 measuring a new rule elsewhere the reference port's editor is driven through its own bridge the probes as a package's Editor assembly, triggered by a file OPEN: it waits on the package's name and on installing the package into a project (Appendix B)
9 scope the toolkit ported effects; the rest of a game had a written route only a topic-by-topic route (BASICS.md, now Chapter 5) and tooling for the code inventory, the transforms and shear, and game-rule parity PARTLY DONE: u2ue inventory, u2ue shear with u2ue.transform, u2ue parity and the runtime library, each with plants; since then the host templates, u2ue host, u2ue scene, u2ue ui and the audio plugin. Animation and physics are not covered (Appendix B)
10 layer_gate.py, host_gate.py the two gates that keep a model engine-free ran on one game's tree (host_gate took no root) a root argument each, run by check DONE: --layer and --root --scan --hosting; the old defaults byte-identical; u2ue check --only model; two planted project files FAIL

What a senior will ask

Why convert through an IR instead of reading Unity and writing Unreal in one pass? The IR is the seam between the two engines. It is plain JSON, testable offline without either editor, diffable between runs, and the only thing a different Unity version changes is the reader. The converter never opens a Unity file.

Why Python inside Unreal and not C++? The stack-writing API (FXConverterUtilitiesLibrary) is exposed to Python, runs headless (UnrealEditor-Cmd) and needs no engine rebuild. whole_trace.py can replay the same Python against a recording stub outside Unreal, which is what makes every change provable in about 100 seconds. What runs in the game at run time (spawning the systems) is the game's own code, not the tool's.

Why so many switches? Each route shipped as a staged rollout: OFF until its trial held, then ON, with VFXPORT_<NAME>=0 still able to switch it off for an A/B against the old behaviour (Chapter 21 counts them, generated). The cost is the dead OFF branches of review finding 7, to be retired in one pass that whole_trace.py proves (the trace with the flipped set ON must not move).

Why does the lane hold so many queue scripts? They are the reference port's job history: each trial's exact orchestration, kept so any result can be re-run. They are not the tool. A new project runs a trial as data with u2ue trial (Chapter 3).

What is not general yet? Measuring a new rule in another studio's Unity editor (review finding 8, and I7 below). A measurement window drives the editor through a bridge that is the reference port's own; the plan is the probes as a package's Editor assembly, triggered by a file, so no recompile runs per measurement (Appendix B). Until then, a measurement in another project is a set of steps its owner runs (Chapter 8).

Reading order for a reviewer

When the diagrams have been followed and it is time to open the toolkit's own documents and code, in this order:

  • u2ue/GUIDE.md - the route for a second project's effects, its rules and its traps (Chapter 7).
  • u2ue/BASICS.md - the rest of the game, topic by topic (Chapter 5).
  • u2ue/USECASES.md - the use case model, its epic, and the requirements it inferred (below).
  • u2ue/adapters/__init__.py - the ports.
  • vfxport/build_niagara.py - build_emitter and its _stage_* functions (Chapter 18, "Inside the converter").
  • vfxport/whole_trace.py - how any converter change is proven (Chapter 9).
  • u2ue/README.md - every tool, by work package (Chapter 18).

The use case model in full

Chapter 17 is the use case model, generated from the toolkit's own documents (the manual's procedures, the toolkit's skills, u2ue/USECASES.md, the verb registry and the pillars). u2ue/USECASES.md is the hand-written model: the problem story, the stakeholder requirements in the owner's words, the epic EPIC-1 ("port a Unity game to Unreal and show how identical it is"), and the requirements the chain inferred that nobody had written. uml.py check gates it: a class or method it names must exist in the code ("Verifying the model", below). This section keeps what the hand-written model adds to Chapter 17: how it was made, the code behind each epic step, four cases of its own (UC-1 finding, UC-6 the transform chain, UC-10 review, UC-11 speed), and the inferred requirements. The UC numbers here are the hand-written model's own; Chapter 17 numbers its generated cases separately (its UC-01 is a converter route).

How the model was made

The model's mode is clone-and-change: the reference product is one whole Unity game running on Unreal (its rules, scenes, UI and effects), and u2ue is the tool extracted from it for OTHER games. The model says what a porter must be able to do with the toolkit, and which of those steps the toolkit does today (HAVE, with the symbol) or nobody had built or specified (INFERRED). Its one rule of authority: the only authored requirements are the toolkit owner's own words, quoted with their dates in u2ue/USECASES.md. The toolkit's own documents were written by the agents doing the work, so they describe and do not require; nothing in the model cites one as a requirement.

EPIC-1 Port a Unity game to Unreal and show how identical it is

Chapter 17 draws the epic's flow and dresses it (scope, actors, trigger, guarantees), generated from u2ue/USECASES.md. This section adds what the generated page leaves out: the code each step runs today. The supporting actors are the owner's Unity editor, the Unreal host and the game owner.

The main success scenario (each step's result is the next step's precondition):

# step what it needs the code that does it
1 the porter finds what the toolkit holds for their question one entry point search() behind py -m u2ue find
2 the porter describes the project: the Unity root and version, the Unreal project, the work folder, the adapter a project file load() of Project, for_project()
3 the tool inventories the game: every MonoBehaviour, the Unity APIs it calls, the scenes and prefabs, the effects a reader of the game's C# and scenes inventory() behind py -m u2ue inventory (kinds, the Unity API by family including value types, pure rules, frame order); the effects through particle_prefabs()
4 the porter, or an agent through the logic skill, moves the rules out of the MonoBehaviours into an engine-free model, behind a platform seam and a view seam the lifecycle mapping, and a gate that the model knows no engine scaffold() (the Core, its tests, the model block), model() of check (the layer and host gates on any project), the runtime library (UnityFrame, Coroutines, PlaybackQueue); the skill (Chapter 5)
5 the porter implements the Unreal adapters for those seams: view, input, camera, effect player, platform services the seams' interfaces and a worked example the toolkit's templates (u2ue/templates/unreal/U2ue.Unreal); the reference port's own hosts are the worked example, found through find
6 the tool converts the transform chain and the scenes: axes, units, rotation order, scale, hierarchy one stated conversion, and a refusal where Unreal cannot hold Unity's matrix inside the effect converter (shape_rotation_writes(), motion_scale(), build_frame_mesh_renderer()); for scenes u2ue.transform, u2ue shear and u2ue scene (Chapter 6)
7 the tool ports the effects the IR, the converter, a build build_emitter() and its twenty stages; the verbs extract, check, build, read and photo
8 the tool proves parity and reports it records, a read of the result, photos; for game rules the same model run on every engine measure() (tempo), the metrics verb, the acceptance page; for game rules run_cases() of digest (CoreCLR and the Unity version's own Mono, no Editor) and the parity verb
9 the game owner answers the decisions the page asks, and only those the report's decision list the report's decisions

Which procedure carries each step is Chapter 17's use case diagram (each include is labelled with its steps); the procedures are read from the manual and the skills by u2ue/survey/req_harvest.py.

Extensions:

  • 3a. The game's effects are chosen by its code, not by its prefabs: the porter writes an adapter that overrides effect_keys() (HAVE: a game adapter is the worked example, Chapter 18).
  • 4a. A MonoBehaviour WAITS (a coroutine, Invoke, yield): the model never waits, and the wait becomes a step of a turn or a tick. HAVE: Coroutines and PlaybackQueue in the runtime library (Chapter 5).
  • 6a. A node has a non-uniform scale under a rotation: Unity draws a shear Unreal's transform cannot hold, and it must be refused and named, never averaged. HAVE for particles (the converter refuses it) and measured for scenes (u2ue shear; the owner decides).
  • 7a. A rule the conversion needs is not measured: UC-8, the hand-written model's "Measure a Unity behaviour", extends here.
  • 8a. The project's Unity version differs from the one the rules were measured on: versions() names them unverified (HAVE).
  • 8b. A frame differs only because one engine drew one random sample: labelled, never counted (HAVE: the random-draw census, u1e_randdraw_census, which names those keys from the IR alone; Chapter 11).

UC-1 Find what the toolkit holds

  • Primary actors: the porter, an AI agent, a reviewer. Trigger: a question ("how is a hemisphere ported?"). Precondition: none (no project is needed). Success guarantee: every hit says where it lives (file and line).
  • The actor runs py -m u2ue find <words>; everything() reads the sources from disk; search() ranks every entry holding all the words; the actor opens the place named.
  • Extension: a source reads nothing - the search stops, because a silent empty source would answer wrongly.

UC-6 Convert the transform chain and the scenes

  • Primary actor: the porter. Precondition: the inventory (UC-3, "Inventory the game"). Success guarantee: every node's world transform in Unreal equals Unity's, or the node is named with why it cannot.
  • The tool reads each node's local position, rotation and scale; composes the chain as Unity does; converts the axes, the units and the rotation (Unity's Euler order to a quaternion to Unreal's rotator); refuses a node whose chain carries a shear Unreal's transform cannot hold; and places the actor. In the effect converter for particles (shape_rotation_writes(), motion_scale()); for scenes, Chapter 6.

UC-10 Review how it is ported

  • Primary actor: a reviewer. Success guarantee: the reviewer can follow every step from a diagram to the code.
  • The reviewer reads this chapter (found by find), the class diagram drawn from the code, the use cases, and the review's findings and what was changed.

UC-11 Measure the porting speed

  • Primary actors: the game owner, an AI agent. measure() reads each route's first code and its flip off git; the metrics verb reads the build records' machine time; both print with their definitions (Chapter 10). HAVE.

The requirements the chain inferred

What the chain NEEDS that no authored requirement states. Each was checked by a case-insensitive search of the owner's quoted words for its key term, with every hit inspected (a hit inside another word is not a hit); py -X utf8 u2ue/survey/usecase_absence.py re-runs the search, and a term that starts to hit leaves this table.

id inferred requirement needed at today
I1 an inventory of a game's code: each class's Unity API calls by family, which are pure rules EPIC-1 step 3, UC-3 HAVE: inventory(), value types a family of their own
I2 the MonoBehaviour lifecycle mapped to Unreal (Awake, Start, Update, FixedUpdate, OnEnable, OnDestroy to constructor, BeginPlay, Tick, EndPlay) with a worked example step 4 HAVE: UnityFrame and the Unreal template AU2ueFrameActor; the logic skill's step 8
I3 ONE stated conversion of a transform: axes, units, rotation order, handedness step 6, UC-6 HAVE: u2ue.transform (Chapter 6)
I4 a non-uniform scale under a rotation refused and named for scenes, as the converter does for particles 6a particles: refused and named; scenes: measured by u2ue shear, the owner decides
I5 game-rule parity provable for another game (the same model on both engines, compared) step 8 HAVE: run_cases() of digest and the parity verb; proven on a second game's first slice (green, with 2 characterised 1-ULP rows)
I6 a waiting MonoBehaviour (coroutine, Invoke, yield) mapped to a step of a model that never waits 4a HAVE: Coroutines and PlaybackQueue (the model emits events; the host replays them)
I7 a Unity measurement in another studio's editor without the reference port's bridge UC-8 OPEN (review finding 8; Appendix B)
I8 prefab overrides, ScriptableObjects and inspector values carried as DATA, read not retyped step 4 HAVE: u2ue data (Chapter 5)
I9 the per-frame order (Unity's script execution order) kept on Unreal step 4 HAVE: inventory() reads each .cs.meta execution order; UnityFrame runs it
I10 time and randomness made deterministic for parity (float32 time sums, seeded randoms) step 8 HAVE: UnityClock, SeededRandom and Digest; the generic particle probe pins every seed

Verifying the model

py uml.py --lang py --root . check --doc u2ue/USECASES.md    # every backticked call the model names resolves in the toolkit's code
py -X utf8 u2ue/survey/usecase_absence.py                    # the inferred requirements' key terms, against the owner's words

The use-case model tests the documents

The toolkit's use-case model is read from its manuals, not written beside them, and measured against the code. Both tools are pillar 3 checks:

  • u2ue/survey/req_harvest.py builds the model from the manuals, skills, use cases, verb registry and pillars, each procedure parsed from its source (a skill's ### Step N. with DO, RUN and DONE WHEN; a chapter's numbered steps); a document it cannot read is refused, never guessed around. Its --selftest refuses a step with no DONE WHEN, an epic include that names no procedure, a procedure with no stated trigger, and a branch naming a step its procedure lacks - which is why this manual's procedures state their Trigger in the text.
  • u2ue/survey/usecase_gaps.py measures against two denominators. Against its own list a model always looks nearly complete. Against the source - every verb, project field, public runtime type, manual page, skill and pillar, READ from the code and files - it lists what no use case owns and prints USECASE COVERAGE n of m, which the cycle holds as a trend. Its --selftest plants a verb no step runs and a chapter never read; both must come back UNOWNED.

Appendix A. A worked example: the reference port

Who this is for: the evaluator - the reference port in numbers: what was ported and how each part was proven, what its effect numbers say, and what the port taught.

The toolkit was built while porting one game, the reference port. This appendix puts that port in one place. Every number is as measured on the date given. It is evidence for the method, not a target for your port.

The game. A turn-based tactics game on Unity 6000.3: painted card units on tiled battle maps, a uGUI battle HUD, and 674 particle effects. All but 7 of them come from three asset-store vendors' packs, which use their own custom shaders. Ported to Unreal Engine 5.7 with UnrealSharp C# hosts.

What was ported, and how

part how the proof
the game's rules moved out of MonoBehaviours into two engine-free assemblies: the rules, and the per-frame presentation layer_gate and host_gate PASS (u2ue check --only model)
the Unreal side thin UnrealSharp C# hosts over the same model three scripted battles on the first battle map - a win, a loss, and a win with a deployed roster - write battle event logs byte-identical to the headless run's (cmp exit 0 on every pair, 2026-09-30)
floats across runtimes the model's digests from Unity (Mono), the Unreal host (CoreCLR) and the headless tests u2ue parity: 383 rows agree, except 35 one-ULP rows in one function where Mono is the odd one out on every row, characterised
the HUD the uGUI canvas captured and laid out by a port of uGUI's solver, painted in one widget held to Unity's own pixels on every captured state (Chapter 6)
sound voice and gain chosen by the model; procedural clips played as PCM through a C++ bridge Chapter 6
levels glTFast export, Interchange import, a fidelity gate Chapter 6; the rope bridge's shear accepted with its number (63.46 / 55.89 cm)
effects the full pipeline of Chapter 7 below

The effects, in numbers

The current headline numbers are the measured tiles on Why u2ue, printed from their record on every build. What they are made of, as u2ue metrics recorded it on 2026-10-15 and u2ue tempo on 2026-10-14, read as a sample of what the two verbs say (Chapter 10 has the definitions):

  • 674 effect keys: 673 built, 1 refused by the IR reader with its reason. 197 of the built keys carry a named gap. Every key is accounted for: built, or refused with its reason.
  • 7,810 emitters drawn. 374 more are absent exactly as they are in Unity (267 Unity never fires; 72 the game does not start; 35 draw or emit nothing in Unity itself) - these are not gaps. 642 are gaps: Unity draws them and Unreal does not, each named and charged to its root.
  • Coverage 92.4 %: of the 8,452 emitters Unity draws, Unreal draws 7,810.
  • 85.6 % measured: 6,689 of the drawn emitters use only rules measured against Unity; 1,121 carry a named stand-in.
  • The read-back: 20,378 emitter-checks over 22 checks, 17 failures (99.92 % hold), printed STALE because the sweep was older than the newest build: a number that describes builds that are gone is never quoted as current.
  • 31.0 hours of headless build time over 673 keys, a median of 97 s a key.
  • 86 converter routes flipped from off to verified on, median 36.2 h from first code to flip; the 33 flipped alone or in a set of fewer than five took a median of 2.4 h.

Every measured Unity bake behind the converter's rules was taken on Unity 6000.3.16f1, so on any other Unity version u2ue check names those rules UNVERIFIED (S11 of the short version shows it on the second game).

The gaps are the work list. Each gap is charged to its root, so the roots sorted by count say which route brings back the most. On the acceptance page of 2026-10-17 the largest was an enabled shape under non-uniform scale (31 emitters over 20 keys), then the children of a few sub-emitter parents whose routes were not ported, then a vendor shader with no Unreal parent (17 emitters). The converter's side of that list is in Appendix B.

What it taught

  • Move the rules out first. Comparing two engines only became possible once both ran the same model. Before that, every difference was an argument; afterwards each one was a row in a digest.
  • Measure, don't recall. Most of the converter's hard cases (sub-emitter frames, ring buffers, sheared nodes, mesh alignment, trails) behaved differently from what the documentation and intuition said. Each became a probe, a judge and a bake.
  • Count what Unity does not draw. The first acceptance pages charged 348 emitters as gaps that Unity itself never draws.
  • A gate can lie by looking at nothing. Several of the toolkit's own instruments passed while reading an empty set or the wrong folder. Every gate now carries plants, and a check that looked at nothing fails.
  • The look is checked by eye. A metric once improved while the whole scene went black.

Appendix B. Roadmap

Who this is for: the evaluator - what the toolkit does not do yet, the plan for each item, and whose call each open decision is.

An item is done when its observable holds, not when its code is written.

Done for this release

item what shipped
code inventory and frame order u2ue inventory (Chapter 5)
serialized data u2ue data
transforms and shear u2ue.transform, u2ue shear (Chapter 6)
parity and floats u2ue parity, its diagnosis read off the rows (the odd runtime per row)
model gates u2ue check --only model
runtime library U2ue.Runtime: UnityClock, Coroutines, UnityFrame, PlaybackQueue, the platform seam, FloatBits, Digest, TrailLaw
UI layout U2ue.Ui (its own tests hold uGUI's layout and TextMeshPro's to Unity's captures, with no game reference) and u2ue ui convert
Unreal host templates U2ue.Unreal: the frame actor, the pointer, the camera rig, the six platform services, compiled against UnrealSharp
the game's own Unreal project u2ue host: create, install, compile, generate, wire, publish, run, each step judged by its proof line (Chapter 3)
audio U2ueAudio: the PCM bridge as a plugin in the host template, its build and its headless play proven: the self test's 440 Hz tone, captured from a headless -game run on 2026-10-15, passes its judge, and pillar 1 of u2ue cycle re-judges it (Chapter 13); authored clips import as Sound Waves directly
prefab instances that remove objects m_RemovedGameObjects applied in the nested-prefab expander: the object, its child subtree and their components leave the instance. An instance that ADDS objects or components (m_AddedGameObjects, m_AddedComponents) is still refused by name
effect point lights read, mapped from both engines' source, spawned on the effect; the Unity side measured on lit pixels (nine cases at 1.0000)
this manual Markdown source with generated reference blocks, a one-page HTML edition, and gates that refuse a page naming one game, a command the facade lacks or a tool file the package does not ship

Game code and subsystems

item plan done when
Host templates: smoke run a headless Unreal run steps a sample model through U2ue.Unreal the run's frame log matches the headless test's
Audio: Unity's sources map a Unity AudioSource and its clips onto the bridge or a Sound Wave; today only the playback path is proven (u2ue cycle pillar 1) a Unity AudioClip / AudioSource ports with no human step
Scenes DONE in part: u2ue scene (export in a window, import, readback, check against the scene's own baseline, with planted faults the gate must refuse). Left: the reference pipeline's middle steps (textures, material parents, lighting, hulls) as verbs a second project's scene goes through all of them with the gate's plants biting
UI capture the capture as the package's Editor assembly; the library's namespace renamed with the package a second game's canvas captured, converted and laid out
Animation and physics not covered. A port needs the Animator's state machines and curves read, and what to measure in Unity first (state timing, root motion, the physics step and contact order) no tool is claimed until a game with them is ported

Effects

item plan done when
Lit materials the URP Lit route (Chapter 7, VFXPORT_URPLIT, default ON, flipped with its evidence) built and photographed against Unity's frames taken under the same lighting, both binormal signs (one axis of Unreal's tangent frame, which may point the opposite way to Unity's) with no whole-frame winner the sign decided by one mesh at a fixed transform lit in both engines; until then Unreal's, named
Point lights, Unreal half the same probe scene in Unreal with the port's light; the judge holds it to Unreal's own formula and reports the pair the pair measured (expected 1 / 0.96 on a diffuse surface: URP's diffuse carries 0.96), the lights of a game's effects LOOKED at in play
TrailRenderer the law is measured and U2ue.Runtime.TrailLaw reproduces Unity's bake on every frame and mesh; a projectile flies an authored curve, so an age-based Niagara ribbon is wrong in flight. The host draws TrailLaw's vertices as a mesh with the trail's material read back and LOOKED at against Unity's trail
Timeline the route is in the converter behind VFXPORT_TIMELINE (default OFF), proven offline (whole_trace: off changes nothing, on changes exactly the predicted emitters) trialled, LOOKED at against Unity's animated frames, the switch flipped with its evidence
Gap roots the converter's remaining refusals - an enabled shape under non-uniform scale, the sub-emitter routes not yet ported, a custom shader with no Unreal parent - each ported in the order u2ue metrics ranks its root by what it brings back each root's emitters drawn, with its route's evidence row
Retire permanent switches delete the OFF branches of switches that are now permanently ON, in one pass whole_trace proves whole_trace shows no engine call moved with the flipped set ON, and the OFF branches are gone

Readers

item plan status
objects in nested models a scene that modifies an object inside a nested FBX is refused; read the model's node ids from its .meta and its transforms from the FBX, or keep scenes on the glTF route planned
one transform module the converter and the trail reader compose transforms through u2ue.transform instead of their own copies planned

Release

The package plan is u2ue/PACKAGE.md: a Unity package installed in the source project, with the parts Unity must not import in folders ending ~ (Tools~/u2ue the facade and tools, Data~/conformance the measured rules, Unreal~/U2UE the Unreal-side builders, Skills~ the agent playbook, Documentation~ the documentation), and the measurement probes as its Editor assembly.

Whose call each item is: the toolkit's, or its owner's (the person who ships u2ue, not the owner of a game being ported).

item plan whose call
No absolute paths the facade and the toolkit's own parts resolve through u2ue/tools.py (U2UE_TOOLKIT_ROOT); many effect, scene and lane tools still hard-wire the reference port's folders as their defaults (PACKAGE.md counts them). Each moves onto the project file's U2UE_* variables, proven by its selftest and an unchanged output the toolkit
The other documents this manual names no game (its build refuses a page that does); the documents it points to - BASICS.md, GUIDE.md, ARCHITECTURE.md, USECASES.md, PACKAGE.md - still use the reference port's names and paths as their examples. Each goes through the same naming gate when it is packaged the toolkit
Probes as an Editor assembly the probes and the window driver ship in the package's Editor/ folder, triggered by a file, with no dependency on the reference port's editor bridge the toolkit's owner: it means installing the package into a project
A second game end to end a second, unrelated game through the whole toolkit: its effects' build, read-back, photos and report, timed from extract onward, are the speed benchmark the toolkit
Packaging package.json, the ~ folders, an install script for the Unreal plugin, a versioned release the toolkit
A player-compile check the headless typecheck never compiles a player, so runtime code calling a member inside #if UNITY_EDITOR passes it and fails in a player build; compile the development player's Assembly-CSharp.rsp the way the typecheck compiles the editor's, its output redirected to a work folder (Chapter 12) the toolkit
The bridge in the package split the reference port's editor bridge into a generic server, the generic routes (Chapter 12's table) and a registration table where a game adds its own routes, which /capabilities lists, so the advert cannot drift from the dispatch. Until then a window and the console gate need a bridge in your project (Chapter 12) the toolkit
Name and licence the package's name, vendor and licence the toolkit's owner
Python or .NET Python stays a dependency of the readers and the facade, or they move to .NET beside the runtime library (the converter runs in Unreal's own Python either way) the toolkit's owner
One package or two whether the game-code part (the runtime library and the method of Chapter 5) ships in the same package as the effects toolkit the toolkit's owner

Two choices are settled, and a port meets both: each game gets its OWN new .uproject, made by u2ue host the way a customer would make one (Chapter 3) - which tests project creation, the plugin install and the host template - and lit effect materials transcribe URP's Lit model rather than being named and left (Chapter 7, "Lit materials").

The release work, in order

The release plan (u2ue/PACKAGE.md) in its order, with each item's state:

# item where it stands
1 Ports and adapters, not a generic game. The three questions that depend on a game (effect_keys, spawn_rules, host_busy) behind one interface, u2ue/adapters; UnityProject answers them for any Unity project, and a game adapter is the worked example of a game that chooses its effects in code. Reviewers start at ARCHITECTURE.md (Chapter 22) DONE
2 The probes in the package's Editor assembly, with the version facts beside them open (Release, above)
3 u2ue check in every run: the selftests, the field gates and the measured rules' Unity versions; red stops the run DONE as a verb (Chapter 9)
4 u2ue metrics and u2ue tempo, and the agent playbooks that ship as the package's Skills~: u2ue/skill/u2ue-port/SKILL.md for the effects and the logic skill of Chapter 5 DONE
5 A second game end to end: its own new .uproject made by the toolkit, which is the speed benchmark. Its first logic slice, through the logic skill, passes parity on CoreCLR, on its Unity version's own Mono and on its own Unreal host (Chapter 5, Chapter 3) under way
6 Packaging: package.json, the ~ folders, an install script for the Unreal plugin, a versioned release open (Release, above)

Appendix C. Glossary

Who this is for: every reader - each term the manual uses, defined in a sentence or two, with the chapter that explains it where one does.

ABSENT - a value the toolkit proved does not exist in the source, or could not read, named with the reason. Never replaced by a default.

acceptance page - the page u2ue report builds from a project's records: every effect key, every gap and every decision the game owner owes; a key never built reads "never built" (Chapter 10).

actor - a role that wants something from the system: a person, the AI model, or the toolkit's own runners (the scripts that, for example, measure Unity in an idle editor: Chapter 17, UC-10); one person can play several roles (Reading UML and use cases).

adapter - the object that answers the three game-specific questions (which prefabs are effects, what starts on spawn, when the host is busy). unity_project is the default (Chapter 18).

aggregate - the one engine-free class that holds an entity's state and rules; the engine's object holds one and forwards to it, so state has one home (Chapter 5).

anchor - the exact text a patch script, or a mutation row, looks for before it replaces it; the patch refuses when an anchor moved or the file already carries the patch (Chapter 14, Chapter 16).

asset family - one kind of asset that ports itself through the same five steps: extract, build, read, judge, photo (Chapter 2).

bake - one run of a probe in Unity, saved as a fact file.

billboard - a particle drawn as a flat quad that faces the camera; Unity drops the camera's roll, Niagara's facing modes keep it (Chapter 11).

bridge - the HTTP server inside the Unity editor that agents and the toolkit's tools call; the reference port's does not ship yet, so a project needs its own (Chapter 12).

capability seam - the optional interfaces an engine implements when it draws more of the game than the base view calls say; a view without one gets the base call instead (Chapter 5).

capture artefact - a photo frame whose difference comes from the capture, not the port (a black frame, a missing texture stream, one random draw); labelled, and never counted for or against the port (Chapter 9).

Cascade - Unreal's older particle system. Epic's CascadeToNiagaraConverter plugin converts it to Niagara; the toolkit uses only that plugin's Python library, FXConverterUtilitiesLibrary (Chapter 3, Appendix D).

census - an offline count over the whole IR, run with today's converter, of the emitters a new route would gain and of what refuses them next (Chapter 11).

class model - which classes a body of code holds and how they use one another, read from the code itself: the game's (u2ue uml, Chapter 5) or the toolkit's (Chapter 22; how to read one: Reading UML and use cases).

Claude Code - the Anthropic tool the AI model works in during a port; it serves most of a session's tokens from the prompt cache (the cost page, Chapter 15).

command - in u2ue's MVC, what the player or the AI asks a scene's Model to do (UseTechnique, EndTurn); the Controller makes it and the Model's Apply runs it, returning events (Chapter 5, "MVC").

concept model - the toolkit's main ideas, each held by one named class, drawn in u2ue/CONCEPTS.md before the code; every cycle, concepts_gate.py checks that each class it names exists (Chapter 22).

conformance - the effects held to Unity on numbers: Unity's own particle state, read by one generic probe, against Niagara's read-back, emitter by emitter (u2ue conform, Chapter 9).

Core - <Model>.Core, the engine-free model's C# project, made by u2ue scaffold, whose only reference is U2ue.Runtime (Chapter 5).

CoreCLR - the runtime of modern .NET: the Unreal hosts and the headless runs execute the model on it, and it can round a float expression differently from Mono (Chapter 5).

coupled and pure lines - the two kinds of C# line u2ue estimate counts: coupled code uses a Unity API, a lifecycle method or a Unity base class; pure code is plain C# (the cost page).

coverage - of the emitters Unity draws, the share Unreal draws: drawn / (drawn + gap).

cycle - u2ue cycle, the toolkit's recurring self-check: every pillar's checks run, each read as PASS, FAIL, HELD or ABSENT, and a FAIL stops the cycle (Chapter 14).

digest - a runtime's per-case output of the game's model, floats as bit patterns, compared by u2ue parity.

domain host - a host interface (I*Host) through which the model asks a question only the game can answer, or makes an announcement only the game can render; it declares domain callbacks only (Chapter 5).

domain reload - Unity reloading the scripts' assemblies after a compile; Unity defers it while in Play (Chapter 12).

DONE WHEN - the observable that ends one step of the logic skill; u2ue logic judges each step by its own (Chapter 5, Chapter 15).

effect key - one effect the game can spawn, usually one prefab; the unit the IR, the build and the report count in.

emitter - one Unity ParticleSystem, and the Niagara emitter built from it.

engine adapter - one engine's implementation of the model's seams: the entity view, camera director, effect player and input source, and the six platform services. Not the project's adapter (Chapter 5).

engine-free model - the game's rules as plain C# that references no engine, run by both engines' hosts.

epic - the summary-level use case that strings the others together; EPIC-1 is the whole port, and each of its steps names the cases that carry it (Chapter 17).

event stream - the ordered, append-only list of events the model writes as it resolves an action; an engine draws only what it says, so everything a player must see is said once (Chapter 5).

evidence row - a switch's row in the flip table: the trial, the Unity measurement and the check that held; a switch is flipped on only with one (Chapter 21).

facade - py -m u2ue, the single entry point; every verb is one row of its registry.

fact file - a probe's output in shared/conformance, with the Unity version that produced it.

file id - the number after & on an object's header line in a Unity YAML file, by which other objects reference it; the IR and every later record pair an emitter by its ParticleSystem's file id (Chapter 11).

flip - turning a converter switch's default from OFF to ON, with an evidence row naming the trial.

gap - an emitter Unity draws and Unreal does not, named with the converter's reason.

gap root - the emitter a gap is charged to: an absent parent's children count against the ancestor that is absent for its own reason, so a root's count is what porting it brings back.

gate - a check that refuses a result breaking one rule (a field gate, the model gates, a scene's fidelity gate) and carries plants it must refuse (Chapter 9).

HAVE / NOT YET - whether the toolkit provides something today; NOT YET is followed by the plan that delivers it (About this manual, Appendix B).

headless - run with no window open and no one needed to answer it, so nothing takes the screen's focus; for Unreal, UnrealEditor-Cmd with -unattended, launched only through ue_headless.ps1 (Chapter 13).

HELD - a cycle verdict: the check fails only in the way a recorded open decision says it must; failing any other way is FAIL (Chapter 14).

host - the engine-side code that runs the model in one engine: Unity's MonoBehaviours, or UnrealSharp actors. Not the Unreal host (below).

hosting folder - model.hosting, the one folder of the model where platform services may be declared (<Model>.Core/Hosting as scaffold writes it); host_gate.py refuses them anywhere else (Chapter 5).

include and extend - the two ways one use case uses another: an include always runs as part of its base (the arrow runs from the base to it); an extend runs only when a condition at one step holds (the arrow runs from the extension to the base) (Reading UML and use cases).

IR - the engine-neutral intermediate representation of an effect: one JSON file per key, read from Unity's YAML.

iron law - u2ue's one principle: propose from a fixed space, verify by execution, report a measured confidence, refuse rather than invent (Why u2ue). Written as working rules for a session: no guessing, no fallbacks, no toys, verify with both the data and the picture (Chapter 15).

judge - a script that holds a record (a fact file, a read-back, a capture) to a rule and refuses it when the rule does not hold. It carries planted defects it must refuse, and is written before the data it judges (Chapter 8, Chapter 14).

land - apply a change already proven on copies (--prove) to the live file (--land); the landing refuses a moved anchor, a file already patched, or a running queue (FAQ).

LOOKED - a picture actually opened and examined by a person or agent. A file that was written has not been looked at.

MEASURED - a value or rule taken from Unity itself by a probe, with the run that measured it.

min-max value - a Shuriken field held in one of four modes (a constant, a curve, a random value between two constants, or one between two curves); the IR keeps it as an object whose readAs says how it was read (Chapter 11, Chapter 21).

miss - in conformance, an emitter judged LATE or EARLY (first drawn on a different frame from Unity's) or COUNT (its live particle count more than max(1, 5 %) from Unity's at a probe time) (u2ue conform, Chapter 9).

Mono - the runtime Unity's editor runs C# on; u2ue digest runs the game's rule cases on the project's Unity version's own Mono, with no editor (Chapter 5).

mutation run - the code under test changed on purpose, one change at a time, to see whether any test notices; the package ships no harness yet (Chapter 14).

MVC - Model, View, Controller: the shape u2ue ports a game's logic into. The Model holds state and rules with no engine type, the View draws, and one Controller per scene turns input into commands and plays the Model's events through the Views (Chapter 5, the u2ue-mvc skill).

MVID - the module version id in a .NET assembly's metadata; the publish proof compares the loaded model's with the one the source just built, to know which build an engine ran (Chapter 5).

owner - the game owner: the person a port is for, who works in the Unity editor a window measures in and answers the report's decisions; a tool that needs that editor waits until the owner is away (Chapter 8, Chapter 12). Not the toolkit's owner, the person who ships u2ue (Appendix B).

pair sheet - one contact sheet per effect, Unity's frames above Unreal's at the same sample times, LOOKED at before a route is called done (Chapter 9, Chapter 10).

parity - the same rule cases answered on every runtime and compared float bit by float bit; a difference is red unless that exact row is characterised, pinned to its bits and to one ULP (u2ue parity, Chapter 5).

pillar - one promise of the product, checked every cycle by u2ue cycle (Chapter 14).

plant - a deliberate defect a selftest feeds a gate or tool; the tool must refuse it.

platform seam - the six services every engine provides and the model never calls directly: the log, text assets, a key-value store, a file store, a JSON codec and a random source (U2ue.Runtime.Platform).

PlaybackQueue - the host's replay of the event stream: one event per frame, only while the views are idle; input waits until it is caught up (Chapter 5).

probe - an Editor C# script that sets up a case in Unity, steps it and writes a fact file.

processed and new tokens - the two token counts u2ue estimate prints: processed is every token a call reads or writes, cache reads included; new is the uncached input, the cache writes and the output (the cost page).

project file - the one JSON file per game, u2ue/projects/<game>.json, naming its Unity tree, its Unreal host and where the work goes; no field is defaulted, so a missing one is an error (Chapter 21).

prompt cache - what serves the part of a model call the model has read before; on Opus 5.5 a cache read costs a twentieth of an uncached input token, so most processed tokens cost little (the cost page).

READ - a value taken from a file, with where it came from.

read-back - the built Niagara systems simulated headless in Unreal, their particles recorded per 1/60 s frame.

requirements model - the toolkit's use cases and requirements, each step citing the page it was read from; Chapter 17, Chapter 19's "Exercised by" lines and Appendix E are generated from it.

resolve - the list of effect keys an adapter writes (work.resolve), which the IR reader reads; extract refuses one whose keys disagree with the adapter's spawn rule (Chapter 18).

route - the converter's handling of one Unity behaviour, behind its own switch.

seam - an interface the model calls instead of an engine API; each host implements it.

selftest - a tool's own check of itself, with plants, run by u2ue check --only selftests.

shear - the skew a rotated child gets under a non-uniformly scaled parent in Unity. Unreal's transform cannot represent it.

shim - a library that declares Unity's value types in namespace UnityEngine, so Unity-shaped code compiles without Unity; not the architecture to build a model on (Chapter 5).

Shuriken and Niagara - Unity's built-in particle system, and Unreal's; the converter turns the first into the second.

sim cache - a recording of a Niagara system's particle attributes, which u2ue read captures frame by frame (Chapter 13).

skill - a packaged procedure an AI model loads when its task matches it; the package ships them under u2ue/skill/, and each ### Step N. carries at least one RUN line and exactly one DONE WHEN (Chapter 15).

slice - one feature's rules, moved into the model at a time, smallest first, and proven by parity before the next is taken (Chapter 5).

STALE - printed beside a number whose input is older than the newest build: it describes builds that are gone and is never quoted as current (Chapter 10).

stand-in - a value or asset the converter used in place of the real one, marked SUBSTITUTED and never counted as measured.

sub-emitter - a child particle system its parent's particles start (at their birth or death, for example); in Niagara the child is an event-spawned emitter (Chapter 11).

sweep - the read-back sweep: every read-back check run over every built system's read, with emitters checked and failures summed per check (Chapter 10).

switch - an environment variable (VFXPORT_<NAME>, U1E_<NAME>) that turns one route on or off.

trend - a pillar check that reads a number and the direction it must not move in; a cycle where it moves the wrong way against the last cycle's value fails, and the first cycle sets the baseline (Chapter 14).

trial - a route tried on real keys in its own content root before its switch flips: built, read back, judged and photographed, from a data file run by u2ue trial (Chapter 7, Chapter 11).

trigger - in a use case, what starts it (Reading UML and use cases); in a window, the file dropped into the Unity project to start a probe or an export, such as .RUN_SCENE_EXPORT, whose one line is the output folder (Chapter 8).

ULP - unit in the last place: the gap between two neighbouring floats. A one-ULP difference is the smallest a float can differ by.

UML - the Unified Modeling Language, a standard set of diagram kinds for software; this manual uses class, use case and flow diagrams (Reading UML and use cases).

UNKNOWN - an answer the toolkit could not reach either way: a lookup that found nothing, or a prefab that nests an asset the project lacks. Never read as ABSENT (Chapter 15).

Unreal host - the Unreal host project the verbs that run Unreal (build, read, photo, host) work in, and the one Unreal slot they share: one headless Unreal at a time, so they refuse while another runs (Chapter 3). u2ue host makes a game its own host project (Chapter 13). Not the same as a host, the code that runs the model.

UnrealSharp - the plugin that runs C# inside Unreal; the Unreal hosts run the model's C# through it (Chapter 3, Appendix D).

URP - Unity's Universal Render Pipeline; the lit-material route evaluates its Lit lighting inside the Unreal material (Chapter 7).

use case - one goal of one actor, told as three to eleven numbered steps that end with the goal reached, plus the ways it can go wrong (its extensions) (Reading UML and use cases).

verb - one command of the facade (extract, build, metrics, ...).

view model - the state as shown on one screen (the HUD, a menu): it moves on only as events finish playing, so the screen never runs ahead of the animation (Chapter 5, "MVC").

view seam - the interfaces through which the presentation asks an engine to draw; every method is a game verb, never an engine primitive (Chapter 5).

whole_trace - the offline proof of a route: the converter run against a recording stub at two versions, and every engine call compared.

window - a short, guarded session in the game owner's Unity editor, started only once the owner is idle, that runs its probes and removes them (Chapter 8).

work package - one group of the toolkit's tools that does one part of a port; Chapter 18 indexes the fifteen.

workflow - a script that runs many AI agents and decides what runs next, so nothing stops at a turn boundary (Chapter 15).

Appendix D. Prior art: other ways to port a Unity game

Who this is for: the evaluator comparing u2ue with the other ways to move a Unity game to Unreal - what each route moves and what it leaves to you, the risks of running C# inside Unreal, the strongest case against an engine-free core, and where u2ue sits.

It covers Epic's own guidance and tools, the community converter, the plugins that run C# inside Unreal, the engine-free cores that middleware and networking products ship, what studios have published about changing engine, and the strongest arguments against the approach u2ue takes. The last section says where u2ue sits among them.

How to read this appendix

The research behind it was read-only and ran in two passes: a search for effect converters on 2026-08-22 (its record is vfxport/README.md), and a wider pass on 2026-09-30, whose second half read the language standards and the .NET runtime's issues as raw text rather than through a summarising reader. Every claim below was read from the source it names, with its link, or is marked ABSENT with what was searched for.

  • Each finding carries a confidence and the reason for it (VERY HIGH, HIGH, MEDIUM, LOW, as the research labelled it), because one blog post and the same answer in three shipped systems are not the same evidence.
  • Products move. Star counts, open issues, supported platforms, versions and last-push dates are as measured on the date given. Any of them may have changed since; read the source again before relying on one.
  • Sources were read as data. Their wording is paraphrased here, with the link to the original.

The routes at a glance

route what it moves what it leaves to you read
Epic's migration guidance assets exported from Unity all code (rebuilt in C++ or Blueprints), Shader Graphs, Timeline and Cinemachine, particle systems 2026-08-22, 2026-09-30
ProjectExodus (community) assets all C# game logic, prefabs as Blueprints, custom shaders, particles 2026-08-22, 2026-09-30
Epic's CascadeToNiagaraConverter Unreal's own legacy Cascade effects everything that comes from Unity 2026-08-22
C# inside Unreal (UnrealSharp) lets moved C# run in Unreal the hosts; anything not exposed to reflection needs C++ 2026-09-30
an engine-free core with a layer per engine (the Spine and Quantum shape) the rules, written once every engine-side object, made again in each engine 2026-09-30
a separate process and a protocol (the chess-engine shape) the core, behind a process boundary the boundary becomes serialisation, and state ownership can split 2026-09-30
change engine and rewrite nothing automatically everything 2026-09-30
u2ue effects converted; scenes, UI and transforms by tools; the code by a method with a runtime, gates and an AI skill moving the code (you, or an AI model with the logic skill), writing the hosts, animation, physics this manual

The 2026-08-22 search covered Fab and the UE Marketplace, the Unity Asset Store, GitHub and Epic's documentation. It found no tool that converts Shuriken effects to Niagara, and named ProjectExodus as the only Unity-to-Unreal project converter. A product may have appeared since.

What Epic and the community converters move

Epic's migration guidance

Epic's page "Migrating assets from Unity to Unreal Engine", read on 2026-09-30, sets the baseline (link):

  • Unity C# scripts and Bolt visual-scripting files cannot be exported from Unity and imported; the functionality is built again in C++ or Blueprints.
  • A Shader Graph cannot be converted to a Material graph. The textures can be exported and the node network rebuilt in the Material Editor.
  • Camera animation and behaviour made with Timeline and Cinemachine cannot be exported; they are recreated with Sequencer.
  • Particle systems are recreated by hand (the 2026-08-22 search, vfxport/README.md).

Confidence VERY HIGH: first-party, read directly.

Read it two ways, because both are true. Epic's baseline assumes the code does not come across at all, and a route that moves the rules into plain C# and runs that C# inside Unreal beats it, and that is a real advantage. But it makes a community plugin the load-bearing beam of the code half of the port, and that plugin's limits are in "C# inside Unreal" below.

ProjectExodus

The leading community migration tool works on assets only and ignores all of the game's C#. It does not turn prefabs into Blueprints and does not support custom shaders (its README, read 2026-09-30, link). The 2026-08-22 search found that it targets Unity 2018.3 and UE 4.25 and does not convert particles. It agrees with Epic about where the work is.

Epic's Cascade converter

CascadeToNiagaraConverter is Epic's plugin for converting Unreal's own older Cascade particle systems to Niagara; it does not read Unity. Its library is still useful to a Unity port: FXConverterUtilitiesLibrary is a Python API that writes Niagara emitter stacks, and it exists only while the plugin is enabled in the project (vfxport/README.md). u2ue's converter writes through it (Chapter 7).

Why engine independence is not paranoia

EA acquired Criterion in October 2004 and later withdrew Criterion's RenderWare engine from the commercial market, stranding its licensees (link). An engine can be taken away. That is a named precedent for keeping a game's rules free of any one engine.

Keeping one game core under two engines

The shipped shape is almost never one core under two engines. It is one core, one engine and one headless server; and where a product really does span engines, it keeps a separate layer per engine, often over a separate core per language, not one binary.

One core, one engine, one headless server

Photon Quantum is the closest commercial product to the engine-free-core architecture. Its documentation credits the split between the simulation (Quantum) and the view (Unity) for the product's modularity. The simulation is a pure C# assembly with no Unity types, Unity is the view, and the same assembly runs on the server as a Quantum plugin. Its events even carry client and server keywords to scope which side raises them, which only exists because one build runs on both. Confidence HIGH: the vendor's current documentation for a product with paying customers, read directly (events, DSL, frames).

SharedMeta (CoreGameIO) does the same for another server stack: one C# game-logic assembly that runs on a server built with Microsoft Orleans and replays on a Unity or .NET client, with optimistic execution, rollback and desync detection; 25 stars, version 0.12.x (link). Confidence LOW as proof that anything works (a tiny project, no shipped title, its README read but not its code), MEDIUM as evidence that the same shape keeps being arrived at.

Middleware keeps two cores, not one binary

Spine (Esoteric Software) is animation middleware shipped in many games on both Unity and Unreal; open source, 5,305 stars on 2026-09-30. Its per-runtime READMEs on the 4.2 branch say:

  • spine-cpp loads and manipulates skeletal animation data in C++ and does no rendering: the engine-free core.
  • spine-ue is built on spine-cpp.
  • spine-unity is built on spine-csharp.

So the Unity path and the Unreal path share neither a binary nor a language. They are two hand-maintained implementations of one documented model, held together by a version rule the repository states: freeze the Spine editor version to the runtime source in use and update the two in lock step.

The presentation layers do not reach parity either. spine-unity claims every Spine feature; spine-ue lists what it lacks: multiply and screen blending, pre-multiplied alpha atlases and two-colour tinting.

Measured from the repository tree on the 4.2 branch, counting only .cs, .cpp, .h, .c and .hpp files and leaving out example, sample, test and demo paths:

part files bytes
spine-csharp (core) 48 599,469
spine-unity (engine layer) 132 1,527,046
spine-cpp (core) 160 1,131,900
spine-ue (engine layer) 39 180,585

On the Unity side the engine layer is about two and a half times the size of the engine-free core. Confidence HIGH: four READMEs read, sizes computed from the tree, not estimated (repository, spine-ue, spine-unity, spine-cpp).

What it means for a port: moving the core is the part the field agrees works. A presentation layer that lags on the second engine is the documented, normal outcome for a mature example of exactly this pattern, and its maintainers' answer was to write the gap down in the README rather than close it.

A separate process and a text protocol

Chess has run one simulation core behind many unrelated front ends since November 2000 through UCI (the Universal Chess Interface), which puts the GUI and the engine in separate processes talking over stdin and stdout (link).

The caveat cuts against a naive reading: under UCI the GUI keeps the board state and decides who wins, and the engine only picks moves. Even the canonical decades-old example splits state ownership, and that split is exactly what makes engine and GUI disagreements a known class of bug there. Confidence MEDIUM-HIGH: the Chessprogramming wiki is a reliable community reference, not a vendor's primary source.

What was not found

No shipped game was found that runs one shared gameplay core inside both Unity and Unreal. Searched: "shared game simulation core across Unity and Unreal engine-agnostic postmortem", "game logic library separate from engine Unity Unreal same C# core adapter interfaces open source", "github engine agnostic game logic C# dll Unity Unreal both adapters netstandard shared simulation", and "we abandoned/we stopped engine abstraction layer game shared core two engines postmortem". The results were patents for simulation-industry middleware, generic engine comparisons and machine-written blogs; nothing primary.

The nearest real thing is Photon itself: Fusion ships for Unity, Unreal and Godot over a shared Photon Realtime C++ core, with a separate SDK per engine (Fusion, Realtime core). That is the Spine shape again: a shared core and separate per-engine layers, not one binary everywhere.

The absence is itself a finding. One artifact under two engines is something the field mostly does not attempt, and where it does (middleware), it maintains parallel code per engine rather than one artifact.

What published engine changes say

  • Slay the Spire 2. Mega Crit built it in Unity for over two years, moved it to Godot after the runtime-fee episode, and stayed moved after Unity backed down. No shared core is reported as extracted; the work was a move, not a bridge. Confidence MEDIUM: press reporting of the developer's statements, not an engineering write-up (link).

The line for a port: moving the core matches what Quantum and Spine do. One artifact running inside both Unity and Unreal has no published precedent, so treat a shared binary as a convenience you happen to get, not as the thing the architecture depends on.

Determinism across runtimes

A port that runs the same C# on Unity's Mono and on CoreCLR (an UnrealSharp host, a headless test run) meets this directly: u2ue compares the runtimes' answers by float bits (Chapter 5, Chapter 14). What the research found, in short:

  • No standard promises bit identity. ECMA-334, the C# language standard (section 8.3.7), says floating-point operations may be performed with higher precision than the operation's result type; ECMA-335, the CLI standard (Partition I, section 12.1.3), says the internal representation may vary until an explicit conversion. A one-ULP difference between runtimes is not a bug, and byte identity across Mono, CoreCLR and a headless run is an observed property of today's builds, not a guarantee: it can break on a Unity or .NET upgrade with no change to the game's code. Confidence VERY HIGH: both read as raw text from the standards' own sources.
  • Two divergences are not rounding, and both are likelier, larger and cheaper to find than a ULP: float-to-int casts, which differ between Mono and CoreCLR, and System.Math transcendentals, which call into the platform's C runtime. Confidence VERY HIGH.
  • Every shipped lockstep success in this literature is one binary on one architecture, and the published desync causes are overwhelmingly not floating point: iteration order, sort stability, serialisation, string formatting, random-call counts, caching. Confidence HIGH.
  • For bit identity across arbitrary hardware, fixed point is the standard answer, at a cost in precision and an overflow ceiling. The modern alternative is not to need it: server-authoritative games compare to a tolerance, not for equality.

So a byte-identical event log across runtimes is a stronger oracle than any shipped game in this literature attempted, and no specification backs it. u2ue keeps it as an instrument and does not assume it ("How u2ue differs", below). The sources, and the checks they suggest for a port's model, are in Chapter 14.

C# inside Unreal

A game whose rules are C# can keep them only if C# runs inside Unreal. All figures here were measured on 2026-09-30 from the GitHub API and the projects' own sites; any of them may have changed since.

UnrealSharp

  • UnrealSharp/UnrealSharp: MIT licence, 1,942 stars, 33 open issues, last push 2026-09-29. Active.
  • It requires Unreal Engine 5.6 to 5.8 and .NET 10.0.5 or newer, and strongly recommends a C++ project (repository, site).
  • It ships games and disclaims production readiness at the same time, and both statements are current. Its homepage lists three Steam titles made with it (Ballistic Brews, Forged: Reconquest, Prompt Crisis); its FAQ still says the plugin is not production ready yet, though the plan is that it will be (FAQ). The FAQ also says up-to-date binary builds are not released consistently, because of the pace of change, so it is compiled from source.

Read that as: it works well enough for small PC titles, its maintainers will not promise more, and its API is still moving. u2ue's Unreal hosts are UnrealSharp C# (Chapter 5), so this is the toolkit's dependency too.

Platforms

From the site's supported-platforms section: Windows and macOS are supported; Linux, iOS and Android are planned; no console appears at all, neither as supported nor as planned. Console and mobile builds are an open feature request, "NativeAOT (Console, mobile)" (issues). A community fork for native C++ transpilation and AOT (ahead-of-time: compiled to native code before the game ships) builds exists, takuma-komatsu/UnrealSharp-dn2cpp, pushed 2026-09-23 with 0 stars: an experiment, not a route. Confidence HIGH: the project's own platform table and the open issue, both read on the day.

If consoles are in scope, the arrangement that runs the model's assembly inside Unreal through this plugin has an expiry date, and the model's boundary should stay serialisable, so that a separate process or a reimplementation could drive it one day. If they are not in scope, this costs nothing.

The trap class

The recent open issues are almost all interop lifetime and marshalling (how long an object lives, and how data is passed, across the line between C# and Unreal's C++) - what you would predict of a managed layer over UObject memory, and a class of bug a logic-parity test does not see. UnrealSharp also reaches only what is exposed to reflection, the same restriction Blueprint has, so anything else needs C++ written by you. The issues as read on 2026-09-30, and the traps a port meets with it and their fixes, are in Chapter 13 and Chapter 16.

The alternatives

option its state on 2026-09-30
UnrealCLR (nxrighthere) 3,305 stars, last push 2023-06-07: over three years dormant. Asked about this exact use, "all game logic in C#, Unreal used as UI only", its maintainer said the plugin accepts compiled assemblies whatever the project's structure, but that interop with managed code from widgets is the biggest problem, that only desktop is supported, and that the project depends on Microsoft and Epic (discussion)
USharp (pixeltris) archived, last push 2020-05-16; its own README said it was not usable for most use cases
Mono-UE a personal side project of several Microsoft employees, supported by neither Microsoft nor Epic (link)
a native core plus a layer per engine the Spine shape: proven, expensive, two implementations kept in lock step
a separate process plus a protocol the UCI shape: proven for decades, but the boundary moves out to serialisation and, in the chess case, state ownership splits between the two sides
reimplement the presentation per engine, keep only the model portable what Spine actually does

Confidence HIGH on the repository facts (measured through the API on the day), MEDIUM on the maintainer's words (read through summaries of the linked discussion, not the raw thread).

The line for a port: UnrealSharp is the only live option, and it is good enough to prove logic parity today. With no console path and no production promise from its maintainers, treat its CoreCLR run as a very good test instrument rather than a shipping commitment. The engine-free model is what keeps the options open if the plugin stalls; callbacks from the model into the engine are what close them.

The case against an engine-free core

This part of the research was told to find the case against. It found one, and not the one expected: it is not "do not separate the core". It is about the motive. The arguments about where the seam is drawn (how many ports, interfaces with one implementor, pass-through layers) are in Chapter 5, for the developer drawing it.

Test the motive

Fowler's YAGNI ("You Aren't Gonna Need It") page names four costs of a presumptive feature: building it, the delay, carrying it, and repairing it. Then it exempts the case that decides this one: YAGNI applies only to capabilities built for a presumptive feature, not to effort that makes the software easier to modify (link).

Run that over the work. Determinism, replay, save-game integrity and tests that need no editor all make the software easier to modify, and they pay this month, on the engine the game already runs on: exempt. A set of adapters for a second engine is a presumptive feature, and it pays build, delay, carry and repair every week until the second engine is real.

So the test: if taking the second engine off the roadmap would kill the appetite for extracting the model, the extraction was never about testability, and the literature will not back it. If it survives that question, it is exempt and the argument is closed. Confidence HIGH on Fowler's text; the test is the research's own framing of it.

The one measured study

BinSubaih and Maddock, "G-factor Portability in Game Development Using Game Engines", CyberGames 2007, University of Sheffield (PDF), built a "Game Space Architecture" - an engine-free game state with an adapter per engine - and ported it between Torque and a second engine. They measured:

  • a CPU overhead of 1.51 % and a memory overhead of 16.49 MB;
  • frames per second down 11.6 % at 55.49 messages per second, with the warning that the game space becomes the bottleneck;
  • data integrity across the different game states at risk: initial tests found no problems, but more were needed;
  • that the approach plainly requires extra work;
  • and, from their own port checklist, the finding that matters most: the game logic is not affected, but while the game objects in the game space stay intact, the ones in the engine have to be created again, and so does the object model.

Confidence MEDIUM-HIGH: peer-reviewed and actually measured, which is rare here, but on a small Torque demo, not a shipped commercial game, so the numbers are indicative rather than transferable.

What it says: the shared core saves the logic, and every engine-side object still has to be created again. The part the architecture protects is not the part the port costs.

The rule of three

Robert Glass, Facts and Fallacies of Software Engineering: Fact 16, reuse-in-the-large (components) remains a mostly unsolved problem, though everyone agrees it matters; Fact 18 restates Biggerstaff's rules of three - a reusable component is three times as hard to build as a single-use one, and should be tried in three different applications before it is general enough to accept into a reuse library (link, restated independently at Coding Horror).

A model extracted from one game has been exercised in one application. By this rule it is two short of known-general, and the three-fold cost is being paid now. Confidence HIGH: a published book, a named researcher, cited independently.

Why studios separate a core

  • BIT.GAMES. Pavel Schevaev, its CTO, on a shipped match-3 with a deterministic C# core split out of Unity, gives five motives: replays, determinism, testing, scripted logic and bot validation. Engine portability is not among them, and he says the overhead may not make sense in small projects (link).
  • Hearthstone runs its rules engine on the server, off the Unity client, for server authority, not portability.
  • Age of Empires separated simulation from rendering because 28.8 kbit bandwidth forced it, and got replays and anti-cheat free as a side effect.
  • Factorio's separation exists for lockstep.

The pattern across every real case in this research: people separate the core for determinism, testing and server authority. In the sources reached, nobody separated it in order to change engines. Confidence MEDIUM-HIGH: four independent cases, but "nobody" is bounded by what was found, not by what exists.

What nobody has published

  • No published case was found of an engine-agnostic core making a real engine port cheap. Searched across Unity to Godot, Unity to Unreal, Unreal to Unity, studio engineering blogs and the academic literature. The one measured study found the port still recreates every engine-side object. That is the hole in the justification for an engine-free core as a porting strategy, and it is stated here rather than papered over.
  • No published breakdown was found of a real engine port's work by part - game code against assets, effects, UI and tools. Epic's documentation answers it qualitatively (code does not transfer; everything visual is rebuilt), but nobody published percentages.
  • Not read, flagged rather than asserted: Casey Yano's Godot evaluation (Medium, 403), the Road to Vostok devlogs (Patreon, 403) and Reddit (unreachable by the search tool). The research spent its search budget part way through and fetched sources directly after that, which is why a few are cited through a secondary restatement rather than their primary.

The Unity MCP server, and what this package adds

A Unity MCP server is the off-the-shelf way to let an AI model drive a Unity editor. It runs inside the editor, so it does what only an editor can, the Unity Test Runner included (its tests-run tool), and this package's second-instance route, my_unity.py, drives it on a clone of the project. Every call needs an open editor, though: the owner's, or a second full editor that takes window focus. Chapter 12 ("Compared with the open-source Unity MCP server") has what was measured against it.

What this package adds:

  • Tests without an editor: the headless NUnit runner, the typecheck, Unity's own Mono through u2ue digest.
  • An editor the owner is not using: idle gating on the cursor and keys, a presence watch, the editor lock, md5-held records.
  • The console as a test: a watermark, collapsed rows, noise counted apart, an exit code.
  • A real editor that is not the owner's: a clone on its own port with the traps of Chapter 12 absorbed, behind a kill switch.
  • Tools that can be trusted: selftests with planted faults, from the runner's planted pass, fail and empty filter to the window runner's simulated editor and every probe judge's plants (Chapter 8).

The window and the console gate still reach the editor through the reference port's editor bridge, which does not ship yet; until it does, a new project needs a bridge of its own (Chapter 12, Appendix B).

How u2ue differs

Measured against the routes above, using only this appendix's sources and the manual's own measured claims:

  • The shape is not new, and that is the point. An engine-free simulation that resolves a step and hands the view an ordered list of events is what Photon Quantum sells and what Epic's Gameplay Ability System does inside Unreal. u2ue's runtime library ships that split as PlaybackQueue<TEvent>: the model resolves an action at once and appends ordered events, and the host shows one per frame and takes input only when it has caught up (Chapter 5). As with Quantum's commands, nothing in the model waits on the view.
  • The model owns the state, the unanimous answer of every source this research read (Chapter 5 has them), and u2ue holds it with gates rather than advice: u2ue check --only model refuses an engine reference in the model and a platform member outside the hosting folder (Chapter 5, Chapter 9).
  • Logic parity is the contract for the code, and it is measured. On the reference port, three scripted battles write event logs that are byte-identical between the headless run and the Unreal host, and u2ue parity compares 383 rows across three runtimes (Unity on Mono, the Unreal host on CoreCLR, a headless test run): all agree except 35 one-ULP rows, each characterised and pinned to its exact bits (Chapter 5, Appendix A). No source in this research had a byte-comparable log across three runtimes; the Age of Empires post-mortem is an account of not having one. Because the standards do not promise bit identity, u2ue does not assume it: a difference is red unless that exact row is characterised, pinned to its bits and to one ULP.
  • It beats Epic's baseline for the code, and does not automate it. Epic's guidance assumes the code does not come across, and ProjectExodus ignores it. u2ue gives the code a method instead - an inventory, an engine-free model, Unity's frame, clock and coroutine rules in a runtime library, gates and parity - and thin UnrealSharp C# hosts. It does not move the code or write the hosts for you (Chapter 1, Chapter 5).
  • It converts the part an engine-free core does not protect. The one measured study found that every engine-side object has to be created again, and that is where u2ue's content tools are. No off-the-shelf Shuriken converter was found on 2026-08-22; u2ue converts Shuriken effects to Niagara through Epic's own FXConverterUtilitiesLibrary, and on the reference port (measured 2026-10-15) Unreal draws 7,810 of the 8,452 emitters Unity draws, 92.4 % (Chapter 7, Appendix A). Scenes are imported and graded by a fidelity gate of 45 checks against the scene's own baseline (on 2026-10-17 the reference port's first map failed 3 of them, each named), and uGUI screens are laid out by a port of uGUI's own solver (Chapter 6).
  • Gaps are written down, as Spine writes its gaps down. Every emitter Unity draws and the port does not is a gap, named and charged to its root, and an emitter one side lacks is named UNPAIRED, never dropped (Chapter 7, Chapter 9, Chapter 10).
  • Its gates can fail. mas-bandwidth/fixed, the fixed-point library of Chapter 14, hashes every result against a constant frozen into its source and ships deliberately broken targets, so that a suite which goes blind says so instead of passing quietly. Every u2ue gate carries planted defects it must refuse, because a gate that has only ever passed cannot be told apart from one that is switched off (Chapter 9).

And what the prior art says u2ue has not answered:

  • UnrealSharp is load-bearing for the Unreal hosts. On 2026-09-30 it had no console path, supported or planned, and its maintainers did not call it production ready.
  • Two games are one short of the rule of three. u2ue has run on the reference port and on a second, unrelated game, whose own Unreal host went from nothing to parity --require Unreal passing in 9 minutes (Chapter 3).
  • There is still no independent published case of an engine-free core making a real port cheap. The reference port is one case, documented in this manual (Appendix A), not an independent one.
  • Animation and physics are not covered (Chapter 1).

Appendix E. Traceability

Who this is for: the reviewer checking that what the toolkit's owner asked for is proven - one table to follow each of the owner's requirements to the selftests that hold it, and to see which ones nothing traces yet.

The chain from what the toolkit's owner asked for to what proves it was delivered: each stakeholder requirement, the steps of the epic that cite it, the use cases that carry those steps (Chapter 17), the verbs those cases prove with (Chapter 19), and each verb's selftest with its last verdict. Everything here is generated from u2ue/USECASES.md, the use case model (Chapter 17) and the selftest registry. A requirement that the epic does not cite is listed as untraced, not as met.

Stakeholder requirement to selftest

stakeholder requirement said epic steps carried by proven with their selftests
Q1 "once this is done you will be able to convert unity projects over rather easily. That is a goal as well. Good architecture." (2026-09-26) - - - -
Q2 "porting another game will merely require implementing the adapters or interfaces." (2026-09-27) step 4, step 5 UC-11, UC-15, UC-16, UC-17 check, cycle, data, digest, estimate, host, info, inventory, logic, metrics, parity, port, report, scaffold, ui, uml check ABSENT; cycle passes (exit 0); data passes (exit 0); digest passes (exit 0); estimate passes (exit 0); host registered, never run; info ABSENT; inventory passes (exit 0); logic passes (exit 0); metrics ABSENT; parity passes (exit 0); port passes (exit 0); report ABSENT; scaffold passes (exit 0); ui passes (exit 0); uml passes (exit 0)
Q3 "I want the work packages so that any game can be ported to unreal. make it a bag of tools with a facade api." (2026-10-13) step 2 UC-11, UC-18 build, check, cycle, data, estimate, extract, info, inventory, logic, metrics, photo, port, read, report build ABSENT; check ABSENT; cycle passes (exit 0); data passes (exit 0); estimate passes (exit 0); extract ABSENT; info ABSENT; inventory passes (exit 0); logic passes (exit 0); metrics ABSENT; photo passes (exit 0); port passes (exit 0); read ABSENT; report ABSENT
Q4 "We wnat to make this a unity package which claude will use to port games. And we will do metrics on the porting speed of opus with these tools and the percent identical" (2026-10-14) step 8, EPIC-1 (success guarantee) UC-07, UC-11, UC-16, UC-18 build, check, cycle, data, digest, estimate, extract, host, info, inventory, logic, metrics, parity, photo, port, read, report, scaffold, uml build ABSENT; check ABSENT; cycle passes (exit 0); data passes (exit 0); digest passes (exit 0); estimate passes (exit 0); extract ABSENT; host registered, never run; info ABSENT; inventory passes (exit 0); logic passes (exit 0); metrics ABSENT; parity passes (exit 0); photo passes (exit 0); port passes (exit 0); read ABSENT; report ABSENT; scaffold passes (exit 0); uml passes (exit 0)
Q5 "I dont' wnat to be ggeneric I want to make a tool to help other port to unreal that's all." (2026-10-15) - - - -
Q6 "so there should be adapters that you implemnet or interfaces etc etc" (2026-10-15) step 2, step 5 UC-11, UC-15, UC-16, UC-17, UC-18 build, check, cycle, data, digest, estimate, extract, host, info, inventory, logic, metrics, parity, photo, port, read, report, scaffold, ui, uml build ABSENT; check ABSENT; cycle passes (exit 0); data passes (exit 0); digest passes (exit 0); estimate passes (exit 0); extract ABSENT; host registered, never run; info ABSENT; inventory passes (exit 0); logic passes (exit 0); metrics ABSENT; parity passes (exit 0); photo passes (exit 0); port passes (exit 0); read ABSENT; report ABSENT; scaffold passes (exit 0); ui passes (exit 0); uml passes (exit 0)
Q7 "when people or seniors review HOW you port to unreal it should be logical and effecient and simple as possible to grasp or elegant" (2026-10-15) EPIC-1 (stakeholders and interests) - - -
Q8 "the guide focuses on shuriken and niagra but what about all the monobehavior methods and transform chain etc" (2026-10-15) step 3, step 4, step 6 UC-11, UC-12, UC-15, UC-16, UC-18 build, check, cycle, data, digest, estimate, extract, host, info, inventory, logic, metrics, parity, photo, port, read, report, scaffold, scene, shear, uml build ABSENT; check ABSENT; cycle passes (exit 0); data passes (exit 0); digest passes (exit 0); estimate passes (exit 0); extract ABSENT; host registered, never run; info ABSENT; inventory passes (exit 0); logic passes (exit 0); metrics ABSENT; parity passes (exit 0); photo passes (exit 0); port passes (exit 0); read ABSENT; report ABSENT; scaffold passes (exit 0); scene passes (exit 0); shear passes (exit 0); uml passes (exit 0)
Q9 "these are basic porting things not answered by the documentation. create the UML fully built documentation as well and use cases and review the architexture with the UML" (2026-10-15) - - - -
Q10 "I want the facade to be the single entry point if possible to at least find everything" (2026-10-15) step 1 - - -
Q11 "STOP GUESSING", "NO fallbacks", "no toys" (the IRON LAW, CLAUDE.md) (2026-08-22) step 9, EPIC-1 (minimal guarantee) UC-11 cycle, estimate, info, inventory, logic, metrics, port, report cycle passes (exit 0); estimate passes (exit 0); info ABSENT; inventory passes (exit 0); logic passes (exit 0); metrics ABSENT; port passes (exit 0); report ABSENT
Q12 "every effect the game fires draws in the Unreal build as Unity draws it, and every gap is named" ('s acceptance) (2026-10) step 7, step 8 UC-07, UC-11, UC-13, UC-16, UC-18, UC-20 build, check, cycle, data, digest, estimate, extract, find, host, info, inventory, judge, logic, metrics, parity, photo, port, read, report, scaffold, tempo, trial, uml, window build ABSENT; check ABSENT; cycle passes (exit 0); data passes (exit 0); digest passes (exit 0); estimate passes (exit 0); extract ABSENT; find passes (exit 0); host registered, never run; info ABSENT; inventory passes (exit 0); judge ABSENT; logic passes (exit 0); metrics ABSENT; parity passes (exit 0); photo passes (exit 0); port passes (exit 0); read ABSENT; report ABSENT; scaffold passes (exit 0); tempo passes (exit 0); trial passes (exit 0); uml passes (exit 0); window passes (exit 0)
Q13 "the primary objective is the unity tool which I would be selling that's the product here" (2026-10-16) - - - -
Q14 "we want them only to port logic the rest should be automatic and for the logic we should build the prompts such that we can just direct opus 5.5 at the game" (2026-10-16) step 3, step 4 UC-11, UC-15, UC-16, UC-18 build, check, cycle, data, digest, estimate, extract, host, info, inventory, logic, metrics, parity, photo, port, read, report, scaffold, uml build ABSENT; check ABSENT; cycle passes (exit 0); data passes (exit 0); digest passes (exit 0); estimate passes (exit 0); extract ABSENT; host registered, never run; info ABSENT; inventory passes (exit 0); logic passes (exit 0); metrics ABSENT; parity passes (exit 0); photo passes (exit 0); port passes (exit 0); read ABSENT; report ABSENT; scaffold passes (exit 0); uml passes (exit 0)
Q15 "We will keep working on UML class diagrams as the steering mechanism for AI" ... "as object oriented as possible in ways that give 'bones' to concepts" (2026-10-16) - - - -
Q16 "Let us add these pillars and check them cyclic" ... "we will need to include all the unity AI tools which they will need to run the tests and to automate unity or unreal like we do" (2026-10-16) - - - -

Read from u2ue/USECASES.md (the stakeholder requirements, in the owner's words; a game's name or a machine path is shown as <game> / <path>) and the use case model (Chapter 17): an epic step is carried by the use cases the model links to it, and a use case proves with the verbs its steps' proof commands run.

Not traced to the epic - each is cited only where named, which is a gap in the epic, not a requirement met:

  • Q1: cited in Inferred requirements - the payload, Verification
  • Q5: cited in PROBLEM STORY
  • Q9: cited in PROBLEM STORY
  • Q13: cited nowhere outside the table
  • Q15: cited nowhere outside the table
  • Q16: cited nowhere outside the table

Use case to verb to selftest

use case verbs its steps prove with selftests
UC-01 A developer lands a converter route behind a switch - -
UC-02 A developer answers one game-specific question with an adapter extract, info ABSENT; ABSENT
UC-03 A developer ports a Unity shader's material family - -
UC-04 A developer makes the converter read a rule measured in Unity window passes (exit 0)
UC-05 A developer gives a tool a selftest the check runs check ABSENT
UC-06 A developer adds a verb to the facade find passes (exit 0)
UC-07 The owner checks every pillar of the product each cycle cycle passes (exit 0)
UC-08 The porter holds every key of a build to Unity on numbers conform, trial, window passes (exit 0); passes (exit 0); passes (exit 0)
UC-09 A developer moves a tool onto the project file tool passes (exit 0)
EPIC-1 Port a Unity game to Unreal and show how identical it is - -
UC-10 The toolkit measures a Unity behaviour in the owner's idle editor window passes (exit 0)
UC-11 Prove it before reporting it cycle, estimate, info, inventory, logic, metrics, port, report passes (exit 0); passes (exit 0); ABSENT; passes (exit 0); passes (exit 0); ABSENT; passes (exit 0); ABSENT
UC-12 The porter imports a Unity scene as an Unreal level and grades it scene, shear passes (exit 0); passes (exit 0)
UC-13 Opus ports one effect gap by the route protocol find, judge, trial, window passes (exit 0); ABSENT; passes (exit 0); passes (exit 0)
UC-14 Record the slice and take the next inventory, logic, slice, uml passes (exit 0); passes (exit 0); registered, never run; passes (exit 0)
UC-15 The porter moves a game's code into an engine-free model check, data, digest, inventory, parity, scaffold, uml ABSENT; passes (exit 0); passes (exit 0); passes (exit 0); passes (exit 0); passes (exit 0); passes (exit 0)
UC-16 Record the slice and take the next one check, digest, host, inventory, parity, scaffold, uml ABSENT; passes (exit 0); registered, never run; passes (exit 0); passes (exit 0); passes (exit 0); passes (exit 0)
UC-17 The porter lays out the game's uGUI screens in Unreal ui passes (exit 0)
UC-18 The porter takes a new game from its project file to its first report build, check, data, extract, info, inventory, metrics, photo, read, report ABSENT; ABSENT; passes (exit 0); ABSENT; ABSENT; passes (exit 0); ABSENT; passes (exit 0); ABSENT; ABSENT
UC-19 The owner assembles the toolkit's repository from its own trees release passes (exit 0)
UC-20 Opus runs the effect pipeline from the prefabs to the metrics build, check, extract, info, metrics, photo, read, report, tempo ABSENT; ABSENT; ABSENT; ABSENT; ABSENT; passes (exit 0); ABSENT; ABSENT; passes (exit 0)
UC-21 The porter verifies the toolkit on their machine check ABSENT