Refactor SceneManager / Transform; fix a number of bugs in scene/game object traversal by mitchell-merry · Pull Request #133 · LiveSplit/asr

mitchell-merry · 2026-05-11T12:48:16Z

Another one of the changes I made to asr that I need to upstream...

Why?

I'm now more and more often traversing the gameobject tree in my autosplitters. This has culminated in being able to get a field on a component of a gameobject in a scene: https://github.com/mitchell-merry/autosplitters-wasm/blob/94fbcef38134317b3a5bd7e549a483f18bed17c4/cuphead/src/memory.rs#L170 which does wonders for what's possible.

I have been maintaining a fork with a bunch of tweaks to asr to make this possible, and it's about time I upstream some of it.

Concepts of Scene/SceneManager and Transform/GameObject are a little too interwoven
- I wanted to access GameObject#activeInHierarchy, but it doesn't really make sense to expose that on the Transform directly to me. It's a feature of GameObjects - what if you don't have a transform?
- get_game_object_from_dont_destroy_on_load doesn't really make sense as a specific function, since we can already get the DDoL scene + game objects on arbitrary scenes
Existing logic has some bugs
- We have klass_name in the SceneManager offsets, but this doesn't really make sense there, since that's strictly to do with the version of Mono/IL2CPP
- When traversing root game objects, it actually traverses in reverse

What?

Split operations on a Scene into the Scene struct rather than being on SceneManager
- root_game_objects, get_root_game_object
- Removed get_game_object_from_dont_destroy_on_load (replacement is to get the DDoL scene then call get_root_game_object, like any other scene)
Scene#root_game_objects now reads next instead of prev, so the objects are read in the correct order
Add Transform#find_transform which traverses the game object tree for you via a path of game object names
Split Transform into GameObject & Transform
- Move Transform#get_name logic to GameObject#get_name, add Transform#get_game_object to Transform and make Transform#get_name use the above two
- Move Transform#classes and Transform#get_class to GameObject
Transform#get_class split into GameObject#get_class_mono and GameObject#get_class_il2cpp since the offset of klass.name depends on the mono version / il2cpp version, same way as it does in the regular path dereferencing code
Add GameObject#is_active_in_hierarchy and GameObject#is_active_self, which are self-explanatory

And then a couple things to make this work for Cuphead:

Support getting the SceneManager from the main module (for old versions of Cuphead)
Logic to get the mono object changed between some versions of mono (? or unity), new switch supports this - needs more testing
Allow manual injecting of offsets, this is intended to be temporary while we properly support everything

Testing

TODO:

Test on Mono versions
Test on IL2CPP versions
- since the offsets change here for class name especially.

…t of SceneManager and Scene

…ncy - by just shelling out to the Mono/il2cpp class code

mitchell-merry · 2026-05-11T12:49:20Z


 impl Class {
-    pub(super) fn get_name<const N: usize>(
+    pub fn get_from_component(


"component" isn't accurate here, but there's something in between the component and the class. not exactly sure what it is.

[ ] TODO: figure out what it is

mitchell-merry · 2026-05-11T12:49:55Z

+        }))
+    }
+
+    // TODO it's really dumb i have to split this by mono/il2cpp


we really need to implement some sort of strategy pattern here. The amount of code duplication is getting ridiculous

mitchell-merry · 2026-05-11T12:50:27Z

+                game_object_activeself: 0x5E,
+                game_object_activeinhierarchy: 0x5F,
                klass: 0x28,
-                klass_name: 0x48,


this changes depending on the mono version, which, of course it does.

Now we just store the offset to the object handle, and you have to use mono/il2cpp specific code to get the component

mitchell-merry · 2026-05-11T12:52:37Z

-    /// (and so on), as well as a list of `Component`s, which are classes (eg.
-    /// `MonoBehaviour`) containing data we might want to retrieve for the auto
-    /// splitter logic.
-    fn root_game_objects<'a>(


This makes more conceptual sense to live on the Scene rather than the SceneManager

mitchell-merry · 2026-05-11T12:53:07Z

-
-    /// Tries to find the specified root [`Transform`] from the
-    /// `DontDestroyOnLoad` Unity scene.
-    pub fn get_game_object_from_dont_destroy_on_load(


no replacement for this - get the DDoL scene from SceneManager, then call get_root_game_object as with any other Scene

mitchell-merry · 2026-05-11T12:57:02Z

+
+        iter::from_fn(move || {
+            // TODO check if this is correct on other games
+            let [_prev, next, current]: [Address; 3] = match scene_manager.pointer_size {


note: there's a change here, previously we were using [first, _, third] where first was our next element.

That's wrong: https://gist.github.com/just-ero/92457b51baf85bd1e5b8c87de8c9835e#file-list-hpp it actually causes us to go in the reverse order in the list. That caused me some issues in Cuphead

mitchell-merry · 2026-06-27T01:39:44Z

-                v_table: MonoVTableOffsets { vtable: 0x48 },
-            }),
+            (BinaryFormat::ELF | BinaryFormat::MachO, Version::V3, PointerSize::Bit64) => {
+                Some(&Self {


Not sure why this indented a level... I didn't change any offsets here.

mitchell-merry · 2026-06-27T01:54:58Z

+        const SIG_64_BIT_PE_1: Signature<13> =
            Signature::new("48 83 EC 20 4C 8B ?5 ?? ?? ?? ?? 33 F6");
+        const SIG_64_BIT_PE_2: Signature<13> =
+            Signature::new("48 83 EC 20 48 8B 2D ?? ?? ?? ?? 33 F6");


note: In my testing, newer versions of unity (Unity 6000.4.5f1 specifically) didn't work with the old sig, so I just added this new one

mitchell-merry · 2026-06-27T01:56:05Z

+    /// FIXME: This function is a bandaid while we don't have support for all
+    ///   scene manager versions in asr. We should remove this by supporting
+    ///   those versions without override.
+    pub fn attach_with_offsets(


note: Since getting all of the offsets on every unity version is quite a large task, I'm opting to just support passing in offsets manually for now.

…g the mono object and add getting the scene manager when it's not in the UnityPlayer module

mitchell-merry · 2026-06-27T12:46:02Z

+
+            (pointer_size, base_address)
+        } else {
+            // If it's not in UnityPlayer, then it's in the main module (old unity versions)


note: I'm also adding support for older versions of Unity in this PR (well except for the offsets, which have to be overridden, which I'll do in later PRs)

mitchell-merry · 2026-06-27T12:46:49Z

+                    .ok_or(Error {})
+            }
+            // FIXME: Untested on V2
+            mono::Version::V2 | mono::Version::V3 => {


note: previous logic only ever did the equivalent of the V1 branch - I found that at least V3 (or like, newer versions, don't know if it's actually split on mono versions) have an extra dereference

…efactor

ero-qt · 2026-09-23T19:37:27Z

Hey! Wanna flag some overlap with some of my open PRs:

#165 replaces the hand-kept scene manager offsets with a layout measured per Unity version. That covers 2 of the things this PR carries per version: where klass.name sits, and how a game object's managed object is reached. If #165 merges first, those switches go away here. Your split would then sit on top of the measured builds.

There's also a harness now (#168, #169). It runs the real Unity players from the fixtures repo and checks what asr reads against a known scene, over 19 versions, both 32-bit and 64-bit, Mono and IL2CPP. Two items on your list it could settle:

The reversed root order. Our fixture scene has only one root object, so there's no order to check. I'll add a second one, then a test can catch it.
activeSelf and activeInHierarchy. The fixture already has an object switched off with a child switched on, Hidden and Quux under Baz. Both flags are checkable the moment the API hands them over.

Let me know what you'd prefer. I'm happy to do the fixture side either way. The API split is yours.

mitchell-merry · 2026-09-23T22:24:11Z

So was this comment written with AI? Can you speak to me like a human? I thought I'd only have to deal with that at work.

I don't think it matters much what I do here. I've had PRs open in this repo for ages that haven't been reviewed despite my incessance, and seeing the number you've raised recently I'm fairly sure they're all going to clobber mine anyways.

I think the last thing this change needed was checking all versions of unity, so if you've got all the offsets that's great and makes this a lot easier.

Is this work one that we would actually like to eventually merge, or is it all changing with your work?

ero-qt · 2026-09-24T13:44:34Z

Yes, this should be merged.

#165, #166 and #167 don't touch your API split: Scene owning its roots, GameObject apart from Transform, find_transform, active flags. They only replace the per-version offsets you're introducing here. Should #165 merge first, I'm happy to help with the conflicts.

mitchell-merry added 14 commits April 19, 2026 19:10

first pass - no monov2 support

7988c36

pull v2 changes over

f224c66

Merge branch 'master' into mono-v3-generic-class-field-count-fix

7c3df3e

fix mono v2 mac offset

93df9f2

mono v3 pe fix

d6d3695

add supposed offsets for v2 mono 32 bit, remove prints

b8aca86

clean up some comments

9569dbd

clean up some more prints

8767f40

fmt + cleaning stuff

1a5e036

further cleaning/commenting

dc14769

another one

4f63667

Separate the concept of Transform and GameObject; separate the concep…

6c56fed

…t of SceneManager and Scene

Add isSelf function, add / update more comments

958fbd8

Create get_class_mono/il2cpp which should fix the klass_name discrepa…

f575ae4

…ncy - by just shelling out to the Mono/il2cpp class code

mitchell-merry commented May 11, 2026

View reviewed changes

mitchell-merry added 2 commits May 11, 2026 23:10

come on now

0152784

remove todo comments

25d397b

mitchell-merry changed the title ~~Transform/GameObject refactors~~ Refactor SceneManager / Transform; fix a number of bugs in scene/game object traversal May 11, 2026

mitchell-merry added 7 commits May 11, 2026 23:37

tweak

d078723

Revert changes for scene name and path as string

c974ef2

tmp

e964365

add new sig, add offsets

5ab8c87

update project settings

135f371

add cheat table

305c1c5

add to todo

440ec35

mitchell-merry added 10 commits May 16, 2026 22:59

latest unity version etc

25f596a

create mono::Object and clarify everything

5df5ac0

comments

822dac3

update todo

1b3ed11

Start cleaning

50be285

remove more

1cb0786

more cleaning + formatting

03646e0

Allow manually overriding the scene manager offsets

b54ef8e

Merge branch 'master' into transform-refactor-tweaks

8679e33

Add another fixme

a24f19e

mitchell-merry commented Jun 27, 2026

View reviewed changes

Revert changes to offsets, leave note

63776b0

mitchell-merry commented Jun 27, 2026

View reviewed changes

mitchell-merry added 4 commits June 27, 2026 17:55

Add get_component_mono_object to streamline

972bb5e

Support older Unity versions by splitting on Mono version when readin…

1a29b00

…g the mono object and add getting the scene manager when it's not in the UnityPlayer module

Couple doc improvements

6657b25

Clean up enum variants + remove todo comment

a05a994

mitchell-merry commented Jun 27, 2026

View reviewed changes

mitchell-merry added 4 commits June 28, 2026 19:58

Some more documentation

f323316

Fix the PE UnityPlayer.dll sig code

7f2f828

Merge branch 'master' into mono-v3-generic-class-field-count-fix

c05c8bb

Merge branch 'mono-v3-generic-class-field-count-fix' into transform-r…

cea4ad0

…efactor

ero-qt mentioned this pull request Sep 18, 2026

Rework the scene manager around measured Unity builds #164

Closed

1 task

ero-qt mentioned this pull request Sep 23, 2026

Rebuild the fixtures with a second scene root LiveSplit/auto-splitting-test-fixtures#16

Merged

ero-qt mentioned this pull request Oct 11, 2026

Let auto splitters attach the scene manager with a profile (#174) #195

Open

Conversation

mitchell-merry commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mitchell-merry May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mitchell-merry Jun 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ero-qt commented Sep 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mitchell-merry commented Sep 23, 2026

Uh oh!

ero-qt commented Sep 24, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mitchell-merry commented May 11, 2026 •

edited

Loading

mitchell-merry May 11, 2026 •

edited

Loading

mitchell-merry Jun 27, 2026 •

edited

Loading

ero-qt commented Sep 23, 2026 •

edited

Loading