Long time no see. I'm currently trying to make a SFX player audio plugin based on AudioResource, a new base class that covers both AudioClip and AudioRandomContainer (Unity 6 addition).  I have several questions that the document didn't go into details that I had to research myself. I hope this article can impart this niche knowledge to those interested.

I'll start with reiterating prior behaviours first. (The gang consists of : AudioMixer AudioMixerGroup AudioSource AudioClip)  Then I'll get to the AudioResource and AudioRandomContainer which is our new stuff whether they conform to the previous functions or not.

Small notes : There are graph time scheduling bug on AudioRandomContainer plays when I test it on 6000.0.50f1, where pausing the game time or the editor will mess with its pulse/offset feature causing it to "miss" the schedule. It seemed to be fixed in 6000.0.59f2. So if you are still on older version please update before playing with it.

Test Set

For audio memory testing, I'll use this long audio file with 10 MB original size and 3.8 MB compressed size. And I'll change up Load Type and Preload Audio Data on each study.

I also have a shorter 1 second file when the test requires a play to end.

AudioMixer and Profiler

In a 2 AudioMixer setup MainMixer + SubMixer, where MainMixer has several of its own AudioMixerGroup, and one called "From SubMixer" that gets the audio from SubMixer.

They are presented in the Profiler like this (showing 4 play one shots currently playing under one of the mixer group) :

AudioClip Memory

If scene has asset reference that eventually leads to AudioClip and it has Preload Audio Data, then it takes memory immediately. How much depends on Load Type. Streaming Load Type cannot have Preload Audio Data.

If Preload Audio Data is not checked, then it is loaded on its first play.

audioClip.UnloadAudioData() can unload audio that was loaded with Preload Audio Data.

Resources.UnloadUnusedAssets() can work similarly to audioClip.UnloadAudioData() without the need to have AudioClip object reference. But the definition of "used" is by following objects in memory, and that means everything in the hierarchy are considered used. Resources.UnloadUnusedAssets() cannot unload the audio memory if some GameObject is still referencing it, even not actually playing it.

AudioSource.PlayOneShot

The argument is still AudioClip, not AudioResource. Therefore you cannot use RandomAudioContainer this way. Understandable, because it is possible to configure RandomAudioContainer to be infinitely repeating according to the playlist.

In the Profiler, stacked PlayOneShot of the same long AudioClip shows up as new "Audio Voices"  without incrementing "Total Audio Sources".

By the way, this "Audio Voices" is what will be subjected to culling according to Max Real Voices in the Project Settings.

If audioClip.UnloadAudioData() is called while PlayOneShot of that AudioClip is playing, it automatically stops all such one shot instances and the memory is unloaded.

While one shot audio are ongoing, changing AudioSource's Volume, Pitch, AudioMixerGroup output will live update all of the running one shot instances. This shows how I can move all the one shots to another place in the mixer tree at once.

On Load Type : Streaming, it seems to take fixed amount of memory (124 KB) to stream the audio no matter how long it is. It has a disadvantage that each stacking one shot instance will need its own 124 KB to stream concurrently, compared to Compressed in Memory or Decompress on Load that each instance can share the same memory. The 2nd image shows that streaming memory is now 248 KB for 2 consecutive streaming plays.

AudioRandomContainer

With a default AudioRandomContainer that plays 2 clips back to back:

The Profiler shows interesting technical aspect that is happening under the hood.

For any AudioSource that had played RandomAudioContainer even once, it starts managing an invisible audio playables called AudioPlayable Group, revealing that the "backend" of RandomAudioContainer is probably playable graphs. If I attempt to change AudioMixerGroup, even if AudioResource is removed from the slot, the Profiler shows that this AudioPlayable Group is being moved to different part of the tree automatically.  

Unlike Play One Shot or Play on AudioClip, the Object name is blank for any plays that occured within AudioRandomContainer. This image below shows "Channels" mode without the groups so you can see that the name is blank. I play both AudioClip way and AudioRandomContainer way at the same time.

Moreover, pausing Unity editor will remove the blank name channels from the Profiler on that frame. Because inspecting the Profiler automatically pauses the editor, you need to move the frame head back by one frame to see the audio played as a part of AudioRandomContainer you want to see.

It appears that there is a short moment where Audio Voices count is 2 while transitioning to the next clip, despite the container didn't allow the clips to overlap.

One more interesting thing is that, while the first sound nest the channel under AudioPlayable Group, at the overlapping moment, and even after, you can see there are one more nested layer of AudioPlayable Group. It seems there is a complex logic that decide how many playable graph group it needs under the hood to run. It should not affect performance, just make this tree a little bit cluttered. 

If we allow short break on the transition, the Profiler now shows a more expected graph which the Audio Voices dropped from 1 to 0 and then back to 1 when the next clip plays.

If you are going crazy on back to back plays, it might worth keeping in mind that short instance where Audio Voices are bloated, just in case you might be close to hitting the limit.

audioSource.Pause() and Unpause() works as expected, if you pause and unpause repeatedly, it will go forward in the sequence bit by bit, including the wait time.

As for memory usage, it seems to do it clip by clip as expected. For example, I have sequential ARC of 10 MB each like this, with Preload Audio Data as false. It correctly starts as neither loaded. And when the ARC is played, only the first one is loaded because the 2nd is scheduled to be played with offset after the first one.

The audioSource.Play() while ARC's Trigger Mode is Manual has a self-overlaying effect similar to PlayOneShot. This is very different from .Play() while the asset is AudioClip which when called repeatedly, it would just abruptly stop and restart the clip. This example shows .Play() called consecutively 4 times, while Trigger is Manual and Playback is Sequential. It results in C and E graphs being added 2 times each. (4 total) Basically .Play() fires a trigger once.

.Pause() and .Unpause() is able to altogether pause all overlapping instances and resume them in one go. Pretty cool actually.

When Trigger is Automatic, it works more like it was previously. Repeated Play() call will restart the whole playlist. For example if it is halfway through "E" and Play() was called again, the E audio abruptly stops and it starts over from the beginning of C.

AudioRandomContainer is also currently not very extensible. The class is internal unlike AudioResource and AudioClip. And attempting to use reflection or direct .asset file writing might be brittle because they don't want you to do that. This is a YAML file of an ARC. Each element added to the AudioClip array is in fact not just AudioClip but AudioContainerElement, because it needs to hold adjustable volume and enabled checkbox per entry as well. Notice how m_Element links to each AudioContainerElement with fileID. (Related article)

Because AudioRandomContainer is entirely internal you lose control on AudioClip that it is made of, for example what if you want to audioClip.UnloadAudioData() to everything that's in the playlist of AudioRandomContainer?

The manual loading and unloading of non-Preload Audio Data clip I think is a critical feature in competent game. In loading screen I'd load all the expected audio so it doesn't introduce unwanted hiccups. The most memorable case for the game I worked on is level up SFX. It's not often that the player leveled up, but it is a very important feedback sound. The fanfare is also quite long so if I didn't preload it, it is guaranteed to skip a few frames of beautiful level up animation. Now imagine that if I went all in to RandomAudioContainer and have a level up audio that would be randomized from 2-3 variations.  Because the API provide no  public way to access those 2-3 AudioClip from AudioRandomContainer , I'd need to separately have reference to them elsewhere, or use reflections. This will quickly complicate things when the game has 300+ sounds each with 2~3 randomized variations.

What about my plugin?

Around 2022 to 2024, I have been developing an audio plugin where it plays everything with audio playable graph. It supports volume, pitch, sequencing, start midway, and chaining up audio playable assets endlessly, etc. It's almost the same feature set you see in AudioRandomContainer right now. I see right away because you are not supposed to be able to play multiple audio with different pitches on AudioSource because adjusting that affects every currently playing audio in real time, unless you do it as playable graph and use the pitch argument in one of the node that's on different branch from the others that goes into the mixer.

My plugin uses concept similar to AudioRandomContainer, able to wrap each AudioClip in a new container that allows per-clip volume adjustment, randomized play, and whatnot. And the name is more generic AudioSet / AudioObject because sometimes it is not supposed to random things. But it has editor tooling to automatically wraps every single AudioClip into the wrapper asset. As a bonus, if you named your audio clips like Foo-1 Foo-2 Foo-3 you get only one Foo wrapped asset that is already setup to randomize the play between 3 versions. It also has a base serialilzable class just like AudioResource.

I took like 1~2 years to finish the plugin, only to discover that in production use when I put my playable-backed SFX slinging engine to test I was flooded by undebuggable FMOD warnings and sometimes runtime error. I had to pivot my plugin hard so everything is played by the old PlayOneShot. Many code documentation about making regular person understand what playable graphs are were already written however, that I have to soon discard them.

Today now that I discovered AudioRandomContainer will end up connecting the audio graph I'm not having very good feeling about this. AudioRandomContainer looks great even if to just wrap a single AudioClip just so you could access its per-asset volume attenuation. But can I really bet my entire game's audio on this?

At one time (2 years ago?) the plugin wire up playable graph like how ARC is doing here. But Unity is so buggy with it (e.g. FMOD error spam I can't make any sense when a lot of audio is played through playable system.) It is clearly not something I can sell to anyone. I actually had my own cases that was unresolved, but since they decommissioned fogbugz and I didn't capture any screenshot I have nothing to show you other than these.

• https://fogbugz.unity3d.com/default.asp?1259935_h4lbeo17t8685ksl
• http://fogbugz.unity3d.com/default.asp?1167289_7t1ofosrlthhs3eo

I had to implement "compatibility mode" that turns the entire plugin into essentially PlayOneShot machine. (This was before the plugin was named "One Shot Framework" and more like SFX Framework) Then life happened, fast forwarded to Unity 6 they came out with what was said in this article. Now, I want to continue developing this plugin, I'm thinking should I use AudioRandomContainer instead of "my class" for the wrapper? Or at least base my base class on AudioResource instead of my own?

After this entire research, the answer is likely no. The whole thing looks feature rich, but inextensible and I had trust issue to commit into it with reflections and direct .asset file writing tricks.

Slightly related, when I test it (2 years ago?) anything audio playables are broken in WebGL build despite this page https://docs.unity3d.com/Manual/webgl-audio.html saying nothing about them. By the way, that page also promises PlayScheduled being supported in WebGL build, which my plugin Introloop heavily uses, but schedule ended up buggy and unusable.

My Evaluation

AudioRandomContainer looks very feature-rich and almost made me wanted to wrap every single AudioClip in my project into AudioRandomContainer. But the opaqueness of the class and how it is playable-backed made me hesitate. The asset being only able to create one by one by hand reliably also discourage me from using it. What if I spent time setting everything up in ARCs and now I found the same FMOD errors later?

For now I will recreate a similar AudioClip wrapping system, except that it should eventually leads to the battle tested PlayOneShot. It's too risky to go all in on ARCs right now. The first step I'd like to see from Unity would be making the class not internal. And at least each AudioContainerElement should be accessible by script.

Unity DOTS is still young so it is rather unclear what other people are doing when trying to accomplish a task. Video tutorials and sample projects are out there but can be hard to gather and verify whether they are the best practice or not.

There is one place we can learn from that has high confidence of being a good pattern, it's any Unity's own packages that references Unity.Entities. This is such as the graphics, the transform, the physics, etc. that the code is surely up to date (because otherwise they wouldn't compile with their own Unity.Entities).

Note : I'll have to keep coming back to update this article as I run into new patterns, since it is impossible to read all codes in all packages just to write this article.

Cleanup component to detect other component's removal

It is stated in the documentation that "This is useful to tag entities that require cleanup when destroyed.". It can be also interpreted in this way : You want to trigger a code when a specific component is gone from both reasons : component remove + entity is destroyed. You create a cleanup component to pair with it.

Use queryWithNone<RealComponent>.WithAll<TheCleanupComponent> detects both ways. Without the cleanup component, just WithNone<RealComponent> would only cover a component's removal and not destroying the entity.

In this usage, you may want to know the content of the component that was just gone. But since it is gone you can't access it now! This is when ICleanupComponent should start having some data from the real component you want to know the last status when it is gone. You will also need to keep the ICleanupComponent up to date with the real one.

In Unity.Transforms package, Parent IComponentData has a pair PreviousParent ICleanupComponentData. There is a work to do on the entity that was the parent of someone, whenever the Parent is removed or when entity with Parent is destroyed.

Per-entity change checking

Check out this article on the bottom :

Chunk’s Change Version

DOTS comes with a per-chunk versioning and a related filter feature. This feature can optimize processing the data only when it mattered.

Game TorrahodSirawat Pitaksarit / 5argon

Tuple array

void AddChildrenToParent(Entity parent, DynamicBuffer<Child> children)
{
    if (ParentChildrenToAdd.TryGetFirstValue(parent, out var child, out var it))
    {
        do
        {
            children.Add(new Child() { Value = child });
        }
        while (ParentChildrenToAdd.TryGetNextValue(out child, ref it));
    }
}

The NativeParallelMultiHashMap from Unity.Collections is "multi" in that duplicate keys are fine. And therefore it could be used as tuple array.

Use if + TryGetFirstValue + do + (while + TryGetNextValue) to iterate.

Helper to add a set of related components

Unlike MonoBehaviour, often one IComponentData won't do anything on its own. Programmer design components much more modularly due to the query feature and linear memory concern, systems often ask for a big set of IComponentData to start working.

How Unity.Transforms and Entities Graphics turns out, user would need to read documentation to learn what components are the entry point to get the systems running, and what components are automatically added after. Such entry point components could use some helping hand from the system programmer.

An example of how to do this comes from RenderMeshUtility.AddComponents in Entities Graphcis package. Send in Entity and EntityManager, and as you expected the inside are a bunch of add components.

public static void AddComponents(
    Entity entity,
    EntityManager entityManager,
    in RenderMeshDescription renderMeshDescription,
    RenderMeshArray renderMeshArray,
    MaterialMeshInfo materialMeshInfo = default)
{
    // ...
}

Inside contains a dynamic ComponentTypeSet generator that has more or less types depending on flags coming in. The ComponentTypeSet is compatible to overload AddComponent(Entity entity, in ComponentTypeSet componentTypeSet). It is created with FixedList128Bytes<ComponentType> and doesn't need manual disposing.

var components = new FixedList128Bytes<ComponentType>
{
    // Absolute minimum set of components required by Entities Graphics
    // to be considered for rendering. Entities without these components will
    // not match queries and will never be rendered.
    ComponentType.ReadWrite<WorldRenderBounds>(),
    ComponentType.ReadWrite<RenderFilterSettings>(),
    ComponentType.ReadWrite<MaterialMeshInfo>(),
    ComponentType.ChunkComponent<ChunkWorldRenderBounds>(),
    ComponentType.ChunkComponent<EntitiesGraphicsChunkInfo>(),
    // Extra transform related components required to render correctly
    // using many default SRP shaders. Custom shaders could potentially
    // work without it.
    ComponentType.ReadWrite<WorldToLocal_Tag>(),
    // Components required by Entities Graphics package visibility culling.
    ComponentType.ReadWrite<RenderBounds>(),
    ComponentType.ReadWrite<PerInstanceCullingTag>(),
};

A system to ensure related components exist

Related to the previous entry, you might instead document that user need to add one component (so you don't need a helper to add multiple components at once) and others will automatically appear. The Entities Graphics package do so by making a system which has only one work of doing the add component by WithAll<ThatOneComponent>.WithNone<ToAdd> queries.

protected override void  OnUpdate()
{
    EntityManager.AddComponent(m_MissingRootLODRange, typeof(RootLODRange));
    EntityManager.AddComponent(m_MissingRootLODWorldReferencePoint, typeof(RootLODWorldReferencePoint));
    EntityManager.AddComponent(m_MissingLODRange, typeof(LODRange));
    EntityManager.AddComponent(m_MissingLODWorldReferencePoint, typeof(LODWorldReferencePoint));
    EntityManager.AddComponent(m_MissingLODGroupWorldReferencePoint, typeof(LODGroupWorldReferencePoint));
}

With this design, those supporting components will be resistant to forced removal since they will immediately come back, and immediately got their value recomputed by an another system that keeps updating their value.

Reusable groups of archetypes

internal struct ResolveSceneSectionArchetypes
{
  public EntityArchetype SectionEntityRequestLoad;
  public EntityArchetype SectionEntityNoLoad;
}

internal static ResolveSceneSectionArchetypes CreateResolveSceneSectionArchetypes(EntityManager manager)
{
    return new ResolveSceneSectionArchetypes
    {
        SectionEntityRequestLoad = manager.CreateArchetype(
            typeof(RequestSceneLoaded),
             typeof(SceneSectionData),
            typeof(SceneBoundingVolume),
            typeof(SceneEntityReference),
            typeof(ResolvedSectionPath)),
        SectionEntityNoLoad = manager.CreateArchetype(
            typeof(SceneSectionData),
            typeof(SceneBoundingVolume),
            typeof(SceneEntityReference),
            typeof(ResolvedSectionPath))
    };
}

Taken from Unity.Scenes, it needs to use this set of archetypes in multiple places. Since you need EntityManager to create an archetype at each place it wants to use, you can create a static helper to create the archetype with EntityManager as input.

Disable tag component

m_PendingStreamRequests = new EntityQueryBuilder(Allocator.Temp)
    .WithAllRW<RequestSceneLoaded, SceneSectionData>()
    .WithAllRW<ResolvedSectionPath>()
    .WithNone<StreamingState, DisableSceneResolveAndLoad>()
    .Build(this);
m_UnloadStreamRequests = new EntityQueryBuilder(Allocator.Temp)
    .WithAllRW<StreamingState>()
    .WithAll<SceneSectionData,SceneEntityReference>()
    .WithNone<RequestSceneLoaded, DisableSceneResolveAndLoad>()
    .Build(this);
m_NestedScenesPending = new EntityQueryBuilder(Allocator.Temp)
    .WithAllRW<RequestSceneLoaded, SceneTag>()
    .WithNone<StreamingState, DisableSceneResolveAndLoad>()
    .Build(this);

This is a simple pattern of creating a tag component to avoid getting worked on by a system (but keep all other components, so as soon as you remove this component it resumes work), by putting it in all WithNone of every queries. They can be next to actual WithNone components that the queries are actually interested in.

This strategy is good when queries are clearly grouped together neatly in OnCreate and component name perhaps starts with Disable so it self-document.

It is from Unity.Scenes where (I think) when editor-only code load a scene it would need a special component to prevent it getting worked on like at runtime.

Request component for reversible operation

In Unity.Scenes, they use a pattern of attaching a component RequestSceneLoaded to a scene entity and their section entities will be loaded. Also when you remove this component, their section entities are unloaded.

You order something to occur with a tag component attaching, and order it to be reversed when the component is removed. Component being able to be added only once helps with work doesn't make sense to occur twice, but make sense to be able to occur again after it is reversed.

This design is different from "request entity" where you create an entity with a component to order a system to do work, then that system try to flag the work as done either by tagging it, using enableable component, or destroying the entity. This design allows the work to occur repeatedly.

using on Allocator 

private void RemoveSceneEntities(EntityQuery query)
{
    if (!query.IsEmptyIgnoreFilter)
    {
        using (var removeEntities = query.ToEntityArray(Allocator.TempJob))
        using (var removeGuids =
               query.ToComponentDataArray<AssetDependencyTrackerState>(Allocator.TempJob))
        {
            for (int i = 0; i != removeEntities.Length; i++)
            {
                LogResolving("Removing", removeGuids[i].SceneAndBuildConfigGUID);
                _AssetDependencyTracker.Remove(removeGuids[i].SceneAndBuildConfigGUID, removeEntities[i]);
            }
        }

        EntityManager.RemoveComponent<AssetDependencyTrackerState>(query);
    }
}

If you are going to use an allocator that requires manual .Dispose, then using block is an option to organize your code.

This article might help you picture the cache while you code DOTS. While you could get by without constantly being aware of cache, it is much more enjoyable to code data-oriented when you know what's going on.

Some component definitions :

public struct ComponentA : IComponentData
{
    public int Data;
}

public struct ComponentB : IComponentData
{
    public int Data;
}

public struct ComponentC : IComponentData
{
    public int Data;
}

If iterating per entity where you have component variable of one entity coming in each time, you can write it either in SystemAPI.Query and IJobEntity like so :

foreach (
    var (a, b, c) in
    SystemAPI.Query<RefRO<ComponentA>, RefRW<ComponentB>, RefRO<ComponentC>>()
)
{
    b.ValueRW.Data += a.ValueRO.Data + c.ValueRO.Data;
}

public partial struct MyJob : IJobEntity
{
    public void Execute(in ComponentA a, ref ComponentB b, in ComponentC c)
    {
        b.Data += a.Data + c.Data;
    }
}

Always backed by a linear array

It is important to understand that the a, b, and c in both styles points to somewhere in a linear native array of just that component. The array of next component comes only after the final element of first component. This is roughly how the chunk looks like.

// The first Execute
[a, a, a, ..., a][b, b, b, ..., b][c, c, c, ..., c]
 ^                ^                ^
 
// The 2nd Execute
[a, a, a, ..., a][b, b, b, ..., b][c, c, c, ..., c]
    ^                ^                ^
    
// The 3rd Execute
[a, a, a, ..., a][b, b, b, ..., b][c, c, c, ..., c]
       ^                ^                ^

Your cache loves this. On the first Execute, on an instant you access that a it will cause a cache miss. But due to cache line being a fixed size (e.g. 64 bytes) larger than the a component (int = 4 bytes) you want,  cache already know the location of 16 consecutive integers as of the 1st execute. Therefore for 2nd ~ 16th Execute, reading/writing to a will result in a cache hit.

The same happened to b and c, it will all cache misses on the first execute then you get bonus hits on some amount of entities coming after. So often, small and modular components results in more automatic performance improvement in DOTS. The sales pitch of DOTS is that if the API is friendly enough for you to make most of your game this way, the game simply will be faster.

But even if you must use large and complex components, even larger than cache line and having a mix of complex sized things like bool in-between, at that point it might get hard to continue picturing the cache while you code. I think you don't have to worry if that is the case, you would still randomly get better performance overall depending on your logic and which fields you access on that large component. There are a lot of effort in Entities that try to align your struct in favor of the cache.

Points to?

Both style of entity iteration looked a bit different, but you can guess the reason that they are trying to accommodate the cache.

public partial struct MyJob : IJobEntity
{
    public void Execute(in ComponentA a, ref ComponentB b, in ComponentC c)
    {
        b.Data += a.Data + c.Data;
    }
}

In IJobEntity style, the design is such that you must either use in (basically readonly ref)  or ref for RO and RW access. Then you read or write these variable normally. The keyword could pass struct by reference instead of by value.

If they are passed by value, the code somewhere (the source generator part) that call this Execute would already cause cache hit / miss way before your code. And that might be bad when you want many kind of components coming in ready for use, but has conditional access and you might ended up not using some of them. It'd be a waste of cache if they are already accessed. (Though even in that case, the cache has a built-in policy that least often used one will quickly get kicked out, etc.) With in and ref, it is only after you touch (read / write) these incoming variables that you do something to the cache and get some bonus hits for next few entities.

foreach (
    var (a, b, c) in
    SystemAPI.Query<RefRO<ComponentA>, RefRW<ComponentB>, RefRO<ComponentC>>()
)
{
    b.ValueRW.Data += a.ValueRO.Data + c.ValueRO.Data;
}

In idiomatic foreach style, the way they want you to write C# doesn't permit adding ref or in there. So the trick is that RefRO and RefRW type using C# property (ValueRW / ValueRO) to facilitate the same "cache only if you touch it in your code". You need a few more . to get to the data and a bit more verbose, but for performance it's a good deal.

Compared with old GameObject way

Disclaimer that I don't actually know how GameObject scattered on your Hierarchy ended up in memory, just a guess it might be this way. The fact that I don't know it, and I know how the memory looks like in DOTS, is already an improvement of DOTS over the old ways...

So you might want to loop through game objects X, Y, Z in an array, with component A, B, C attached on all of them. If  you have an array of GameObject type, then you have an array of pointers. Reading the first element of this array and causing cache miss won't give you any exciting bonus. Supposed that if your cache line is very big, the best is you know the address of the next GameObject, not its data you are interested in.

// 1st iteration
Array of objects : [X, Y, Z]
                    ^
                    
// 2st iteration
Array of objects : [X, Y, Z]
                       ^
                       
// 3rd iteration
Array of objects : [X, Y, Z]
                          ^

Somewhere in the memory : [(X)Transform, a, b, c]??????????[(Y)Transform, a, b, c]???[(Z)Transform, a, b, c]?????

Then you might have to get each component individually and cause an another jump. If memory is really looking this way, with mandatory Transform component or other custom components you are not interested in right now, with ???? being unknown length, and before DOTS you don't care since you are going pointer-happy and jumps repeatedly without caring the cache, the cache line will rarely get good bonus data that is useful in the next iteration loop. The a data of each GameObject are so far away from each other.

Burst and SIMD : Automatic vectorization

The cache line bonus thing of reading the first int and knowing 15 more int can be further improved. What requested data from cache is not your C# code but a compiled assembly code. C# code might looks already cache-friendly, but choosing the right assembly code can push the limit of cache-friendliness further.

public partial struct MyJob : IJobEntity
{
    public void Execute(in ComponentA a, ref ComponentB b, in ComponentC c)
    {
        b.Data += a.Data + c.Data;
    }
}

Look at this work again. I mentioned that on the first read of a, you would automatically get future a into the cache for the next loop. But before you get to the next loop, you must also read c, read b, then write to b, to get to the bonus a waiting for you.

But how about using all those future a in one loop, the same for b and c too?

If you mark the job for Burst compilation, it can look at anything looping ("scalar code", which in DOTS is common, and looked natural for the programmer) and rewrite them such that it performs the work of many consecutive loops in one go, becoming a "vector code".

It is a good job for machine to do for you since manually writing vector code often mask your actual intent with a lot of optimizations. Imagine if you are writing such that it perform 4 loops worth of work in one. Not only you need to pack up the variables and somehow make sure it became the right vector assembly command (depending on the target machine's processor), if the last loop ended up not adding up to 4 you must do the remaining in scalar way. Imagine doing that by hand on every loop in the game?

Let's slap on [BurstCompile] right now and see how smart it is. I'll add a constant 1234 into the mix just so it is obvious in the AVX2 assembly in the Burst Inspector. I like selecting AVX2 for performance debugging because it introduces 256 bits commands. It is obvious when Burst is trying to take advantage of them.

[BurstCompile]
public partial struct MyJob : IJobEntity
{
    public void Execute(in ComponentA a, ref ComponentB b, in ComponentC c)
    {
        b.Data += a.Data + c.Data + 1234;
    }
}

The Burst Inspector comes with useful debug mode ("Coloured With Full Debug Information") that makes it easy to spot if it is doing the expected tricks. Here, you can see the comment saying about making an 8 element array of repeated 1234 (that means this one ymm register fits 8 int, 32 * 8 = 256 bits register), which is not exactly what you wrote, but it is clearly cooking. Pink instructions indicates vector assembly command, they starts with v. In other words, pink is good.

And then you see the effort of utilizing this chunky ymm_ register.

Interestingly, it tries to go beyond and even double up each command, using both ymm1 and ymm2 as its workbench at the same time. So this is like working on 16 int consecutively, even though one vector command supports only up to 8 int. I could see this double up of work might be to take advantage of bigger cache line. (The +32 bytes offset is the size of 8 int.)

After reading out 8 + 8 int from the native array of B (r14, you can see on DEBUG_VALUE too), adding rax and rbx is adding multiple integers from A and C respectively. The preparation of ymm0 (eight 1234) earlier is then  added to everything.

The following add cmp jne is that leftover loop thing I talked about. If the remaining works are less than 16 int (the 64 you see is the size of 16 int) , then...

It will finish up the rest one by one without vectorization. rsi moves forward by 4 bytes each time so that's surely one int each, and you see that r14, rax, rbx casts are the same, and topped up with 1234.

This is wonderful that you get all these insane code (both the vectorized part and scalar part) without writing them!

DOTS comes with a per-chunk versioning and a related filter feature. This feature can optimize processing the data only when it mattered.

This article highlights where they are in the API and their behaviour / quirks.

Utilizing the change version

Using a filter

The query way provides an easy to use filter system.

• On SystemAPI.Query idiomatic foreach :  QueryEnumerable<T1> has .WithChangeFilter you can use, with <T> and <T1, T2>. So you can't add more than 2 components to check changed status at the same time.
• For SystemAPI.QueryBuilder(), you must .Build it first, then there is .AddChangedVersionFilter you can use. This call is additive, but inside the source code, there is still a hard-coded limit of 2 components to filter on change version. (i.e. Error if you .AddChangedVersionFilter 3 times.)

Both ways you can have max 2 components to check, so this is an important number to keep in mind when designing your logic. Also take note that the noun is either "change filter" or "changed version filter" (with the -d). But the thing that is stored per-chunk to make this feature work is called "change version" number (without the -d), explained in the incoming section.

The query has .IsEmpty which account for the filter, unlike .IsEmptyIgnoreFilter version. In Unity's code there are many early out optimization with .IsEmptyIgnoreFilter in main thread code. You maybe able to do similar thing too.

Manual checking on chunk iteration

However if you decided to get more involved with per-chunk iteration (IJobChunk) there is no longer a convenient filter to help you. You can use .DidChange available on ArchetypeChunk that is given you per iteration. By more involved, you now have to go through the trouble of bringing in these into the job :

• The system's uint last version number : Obtained from SystemState.LastSystemVersion. "Last" meant the last time (not this time) that the system updates, what was its version?
• The ComponentTypeHandle<T> : Obtained from SystemAPI.GetComponentTypeHandle(isReadOnly: true). Note that they designed it like this so that there are hoops you must jump through in order for the system to be notified of type's read dependency on the job it is going to schedule / run.

public struct ChunkJobWithChangeFilter : IJobChunk
{
    public ComponentTypeHandle<SampleDataComponent> SampleDataComponentHandle;
    public uint LastSystemVersion;

    public void Execute(in ArchetypeChunk chunk, int unfilteredChunkIndex, bool useEnabledMask,
        in v128 chunkEnabledMask)
    {
        if (chunk.DidChange(ref SampleDataComponentHandle, LastSystemVersion))
        {
            // Do something
        }
    }
}

This chunk-based way you are no longer bound by 2 components limit, and also can if else as complex as you wish. (e.g. If A component chunk is marked as changed, do this. If B component chunk is marked as unchanged, do that instead.)

This chunk-based way also reveals the exact mechanics how it obtains the boolean "changed?", by comparing chunk's changed version number with system's.

How the change version works

This I think is more complicated than using the filter, and official documentation is not making it very clear. There are 3 version numbers in play, to make it easier to differentiate I'm going to mark them with emoji just for this section.

There is a number called  🌍 global system version. This version increases by 1 for each consecutive system updated, including system groups. After each system updates, the system remember this number as its ↩️ last system version. Therefore during the update, its ↩️ last system version could determine when it was updated the previous frame.

Then, there is a per-chunk number called ✏️ change version. How the chunk is considered "changed" in order to update this number is rather crude : Instantly when a query is executed related to that component and it has write permission. Then, chunks returned for that query will all get their ✏️ change version updated.

It does not check whether system actually "change" the component's value with its work using the query. It just see the write dependency and thought the system "probably" changed that for all the matched chunks.

It is per chunk. There are other entities in the chunk that are not actually changed and still get iterated. Your logic must not be destructive to these entities. Try treating changed filter as optimization rather than branching logic, always imagine if the changed filter is removed, everything must still work like before but with worse performance.

To record that the chunk has changed, its ✏️ change verion is updated to the 🌍 global system version. Note that ↩️ last system version is still behind 🌍 global system version during the update. Only after the update that it is also catch up to 🌍 global system version, making it equal to the ✏️ change version it just recorded.

Finally we can get to how it works : If chunk's ✏️ change version is higher than ↩️ last system version then it had changed. ("Had changed since the last time this system updated.", to be exact.) Equal or lower meant it had not changed.

Supposed that System A writes to a component during its update, during the update, chunk's ✏️ change version would be ahead the system's ↩️ last system version for a brief moment (updates to 🌍 global system version). After the update, ↩️ last system version is then updated to be 🌍 global system version to catch up too. (They are equal now.) This means if there is no other system doing anything to this component, the next frame, equal number meant it has not changed and query will not return the chunks.

But supposed that there is a System B following immediately after A and it writes to this component too and recorded a higher ✏️ change version into the chunk, in the next frame System A would be able to detect the change made by System B the last frame.

Tests

To reinforce the learning, here are some tests. Before the tests, I'm introducting 2 actors which is a simple component data (that we are going to change, and check its change version) and a big internal capacity dynamic buffer type designed to bully the archetype to have many chunks, so we could see clearly when change version works on one chunk and not the others.

public struct SampleDataComponent : IComponentData
{
    public int Data;
}

[InternalBufferCapacity(256)]
public struct FatBuffer : IBufferElementData
{
    public int BufferData;
}

Last system version starts out at 0, a special number

The first time the system updates, there is no "last" to look back to, therefore it is 0. Everything is considered "changed". This further emphasis that this feature should be an optimization, if the filter is somehow gone (work on everything) the result should be the same, just that the work might be a bit more redundant.

This code prints the OnUpdate forever with increasing frame number and system version number, but print the foreach exactly 90 times and never again. I name the entity on create so that on logging I could get its name.

public partial struct SystemA : ISystem
{
    public void OnCreate(ref SystemState state)
    {
        var myArchetype = state.EntityManager.CreateArchetype(typeof(SampleDataComponent), typeof(FatBuffer));
        for (var i = 0; i < 90; i++)
        {
            var createdEntity = state.EntityManager.CreateEntity(myArchetype);
            state.EntityManager.SetName(createdEntity, $"Entity No. {i}");
        }
    }

    public void OnUpdate(ref SystemState state)
    {
        Debug.Log($"System A : Update at frame {Time.frameCount}, last system version {state.LastSystemVersion}, current global {state.GlobalSystemVersion}");
        foreach (
            var (sampleData ,entity) in
            SystemAPI.Query<RefRO<SampleDataComponent>>()
                .WithChangeFilter<SampleDataComponent>()
                .WithEntityAccess()
        )
        {
            Debug.Log($"System A : {state.EntityManager.GetName(entity)} foreach at frame {Time.frameCount}");
        }
    }
}

System always update unless...

As evidenced in the previous example, the system's OnUpdate does not care about whether its query get 0 match or not. So in effect this change version feature can't affect the system's workings. This behaviour matches MonoBehaviour one so it is easy to understand.

But you can go advanced and register the query (should be in your OnCreate) with the following methods on SystemState to make the update conditional :

RequireForUpdate(EntityQuery query) : void
RequireForUpdate<T>() : void
RequireAnyForUpdate(params EntityQuery[] queries) : void
RequireAnyForUpdate(NativeArray<EntityQuery> queries) : void

RequireForUpdate<T> is handy for system that is going to process a singleton component.

There is also [RequireMatchingQueriesForUpdate] attribute to paste on top of your system and you don't even have to register anything manually. The system knows its queries and this attribute will add them all to the requirement.

You would imagine pasting this attribute to the previous example will only prints 91 times and stop, but that's not the case (lol!) as both RequireForUpdate and [RequireMatchingQueriesForUpdate] ignores all the filters in the query. (3 kinds : Change version filters, shared component filters, order version filters.) Anyway, preventing the system's update is not our focus here. Let's focus on just whether the query with change version filter works or not.

System version increases globally after each system

The previous example, if you look at frame 2 and beyond, you might be surprised at the system version numbers.

As mentioned, global system version (and therefore also last system version) is also increasing when other systems updates. (There are many built-in ones that came with the package. There are 54 more systems along the way.

Now it is time to introduce a similar SystemB with [UpdateAfter(typeof(SystemA))], it would ended up like this.

public partial struct SystemA : ISystem
{
    public void OnCreate(ref SystemState state)
    {
        var myArchetype = state.EntityManager.CreateArchetype(typeof(SampleDataComponent), typeof(FatBuffer));
        for (var i = 0; i < 90; i++)
        {
            var createdEntity = state.EntityManager.CreateEntity(myArchetype);
            state.EntityManager.SetName(createdEntity, $"Entity No. {i}");
        }
    }

    public void OnUpdate(ref SystemState state)
    {
        Debug.Log($"System A : Update at frame {Time.frameCount}, last system version {state.LastSystemVersion}, current global {state.GlobalSystemVersion}");
        foreach (
            var (sampleData ,entity) in
            SystemAPI.Query<RefRO<SampleDataComponent>>()
                .WithChangeFilter<SampleDataComponent>()
                .WithEntityAccess()
        )
        {
            Debug.Log($"System A : {state.EntityManager.GetName(entity)} foreach at frame {Time.frameCount}");
        }
    }
}

[UpdateAfter(typeof(SystemA))]
public partial struct SystemB : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        Debug.Log($"System B : Update at frame {Time.frameCount}, last system version {state.LastSystemVersion}, current global {state.GlobalSystemVersion}");
        foreach (
            var (sampleData ,entity) in
            SystemAPI.Query<RefRO<SampleDataComponent>>()
                .WithChangeFilter<SampleDataComponent>()
                .WithEntityAccess()
        )
        {
            Debug.Log($"System B : {state.EntityManager.GetName(entity)} foreach at frame {Time.frameCount}");
        }
    }
}

Well, turns out B is not updating immediately after A but rather there are 3 systems that updated between them. You can use the Systems debugger to see what came in-between. There they are.

RW access is enough to update the change version

If I first just remove .WithChangeFilter() from SystemA (retains the RO), I would get SystemA that unconditionally foreach on every frames 90 times per frame, and SystemB which still has .WithChangeFilter() won't update other than the first time, since RO doesn't flag the chunk to get a new change version.

And then I change RO in SystemA to RW, now .WithChangeFilter() on SystemB (still RO) see the change every time since it always run after SystemA, and ended up updating as well on every frames. We can clearly see that write dependency is what caused the change because the logic is just reading and logging.

The query needs to occur for RW to update all the matched chunk's change version. If I put an unlikely if before the foreach, then SystemB will not be notified of the change even though SystemA has RW permission of that component and its OnUpdate occurs.

Change version update is per chunk

Remember that I intentionally make the archetype big enough that there could be just 15 entities per chunk. To test this out, I'll just add a tag component TagForChunk to the last 16 entities when I create 90 entities in SystemA's OnCreate. The result should be that we have 2 chunks of this new archetype that includes the tag. One chunk with 15 entities, another with 1 entity.

Then modify the "work" in SystemA to have RefRO<TagForChunk>. The work stays the same (logging and not actually writing), so this work should update change version of those 2 chunks (because there is still RefRW on the SampleDataComponent) .

And important that in SystemB, everything stays the same including not caring about TagForChunk at all.

public struct TagForChunk : IComponentData
{
}

public partial struct SystemA : ISystem
{
    public void OnCreate(ref SystemState state)
    {
        var myArchetype = state.EntityManager.CreateArchetype(typeof(SampleDataComponent), typeof(FatBuffer));
        var archetypeWithTag =
            state.EntityManager.CreateArchetype(typeof(SampleDataComponent), typeof(FatBuffer), typeof(TagForChunk));
        for (var i = 0; i < 90; i++)
        {
            Entity createdEntity = state.EntityManager.CreateEntity(i >= 74 ? archetypeWithTag : myArchetype);
            state.EntityManager.SetName(createdEntity, $"Entity No. {i}");
        }
    }

    public void OnUpdate(ref SystemState state)
    {
        Debug.Log(
            $"System A : Update at frame {Time.frameCount}, last system version {state.LastSystemVersion}, current global {state.GlobalSystemVersion}");
        foreach (
            var (sampleData, tag, entity) in
            SystemAPI.Query<RefRW<SampleDataComponent>, RefRO<TagForChunk>>()
                .WithEntityAccess()
        )
        {
            Debug.Log($"System A : {state.EntityManager.GetName(entity)} foreach at frame {Time.frameCount}");
        }
    }
}

[UpdateAfter(typeof(SystemA))]
public partial struct SystemB : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        Debug.Log(
            $"System B : Update at frame {Time.frameCount}, last system version {state.LastSystemVersion}, current global {state.GlobalSystemVersion}");
        foreach (
            var (sampleData, entity) in
            SystemAPI.Query<RefRO<SampleDataComponent>>()
                .WithChangeFilter<SampleDataComponent>()
                .WithEntityAccess()
        )
        {
            Debug.Log($"System B : {state.EntityManager.GetName(entity)} foreach at frame {Time.frameCount}");
        }
    }
}

The result is it is as if SystemB has RefRO<TagForChunk> too, but it was all the work of .WithChangeFilter<SampleDataComponent> that results from SystemA working according to the tag. The update starts from Entity No. 74 to Entity No. 90. (15 + 1 entities across 2 chunks.)

Enableable components does not work on chunk level

Enableable component is a feature that works per entity. The source generator will query all chunks, updates the version of RW component of all chunks, then decide for each entity whether it get to work or not.

So if I change the tagging in the previous example to instead disable SampleDataComponent for last 16 entities, because we have 6 chunks, theoretically the final chunk could be skipped entirely. But since it doesn't work that way, all chunks ended up being changed.

Bonus reminder about IJobChunk

When a system run / schedule IJobChunk, the RW or RO permission is decided on whether input ComponentTypeHandle<T> coming into the job (required to get NativeArray<T> from ArchetypeChunk on each per-chunk iteration) was created in the system with SystemAPI.GetComponentTypeHandle<T>(isReadOnly: true OR false).

(There is also [ReadOnly] attribute you could paste on the input to the job, but I don't think it let the system know.)

Advanced : Per-Entity Change Checking

This coding pattern is taken from Unity's official Unity.Transform package, so I think we can trust it as a good pattern?

You want to do heavy work on component value's change. A per-chunk DidChange will work, but other entities not really changed (or worst, the chunk got RW but nothing changed) will also get the work just because an entity in the same chunk changed, only to get the computed result to be the same as they are right now, so it is a useless work.

Solution : By creating a new "previous" component with the same fields to pair with that you want to check for a "real change". (Remembering that some components have a "previous pair" is also a pain, so you might also have to go through trouble of writing a system to automatically add this "previous" component whenever it found a real one.)  You can then put a value comparision check just behind the DidChange's initial rough filter so you can check per-entity if it really changed. Then you update previous to be the present one as well if it ended up changed.

if (chunk.DidChange(ref ParentTypeHandle, LastSystemVersion) ||
    chunk.DidChange(ref PreviousParentTypeHandle, LastSystemVersion))
{
    var chunkPreviousParents = chunk.GetNativeArray(ref PreviousParentTypeHandle);
    var chunkParents = chunk.GetNativeArray(ref ParentTypeHandle);
    var chunkEntities = chunk.GetNativeArray(EntityTypeHandle);

    for (int j = 0, chunkEntityCount = chunk.Count; j < chunkEntityCount; j++)
    {
        if (chunkParents[j].Value != chunkPreviousParents[j].Value)
        {
            // Work...
        }
    }
}

Now for details if you are still interested... otherwise you can end this article here.

In the ECS transforms system, you build a transform hierarchy bottom-up by attaching Parent to an entity and let it say who the parent is. This make it easy to move an entity (along with an entire tree of its children right now) under some other entity by setting just a single entity's Parent component to point to a new one. No need to change any of its children.

But programmer often wants to iterate through children, and knowing just Parent is not so useful. So there is a system that would keep looking at all Parent in the world and figure out the hierarchy tree and maintain the buffer component Child for each entity. As you can imagine, this work is looking to be intensive and must be performant.

The system that do so cannot just work on any new Parent it found and say "Yes, I have already worked on this one" (and perhaps slap a tag component on it), it must additionally :

1. Always actively look for field change inside any Parent component.
2. If the component Parent is removed or the entity with Parent is destroyed, then the affected parent will need their buffer updated.

So how they did it that solve both points at the same time, is to have a "previous" component named PreviousParent with the same field as Parent as a pair. The fact that it is an exact pair solves point 1. This component must be ICleanupComponentData in order to solve point 2.

This component should be automatically added when system detects a new Parent (WithAll<Parent>().WithNone<PreviousParent>()) coming into the world. At this point the previous parent starts by copying the value of the present one. Now you have got a per-entity change checking pattern working! When .DidChange detected a chunk-level change (or just some careless RW), we have a 2nd level check, by perform a linear iteration through native array of Parent and PreviousParent and really see for real if the value differs entity by entity.

Though unrelated with change version topic of this blog post, ICleanupComponentData gives the ability to react to both kinds of removal (remove just the component, or the entity got outright destroyed) with this kind of query : .WithAllRW<PreviousParent>().WithNone<Parent>(). When it detects such moment, PreviousParent serves an another purpose than "true change checking" that is to notify the parent of its deceased child (how sad!) so it could update its children.

The Enableable Component feature is described very succinctly as saving you small trouble of performing the common trick of sticking a bool in a component you want to disable without causing structural change. Also don't forget that you need to write the if checking that bool on your job code to make use of it.

On surface this feature sounds like a nice little thing they added for us, but underneath it has a lot going on.

How many 1234 do you think you would see in the Burst compiled assembly code of this simple standalone job?

public struct JustCounterComponent : IComponentData
{
    public int Valuez;
}

[BurstCompile]
internal partial struct AddCounterJob : IJobEntity
{
    public void Execute(ref JustCounterComponent xyz)
    {
        xyz.Valuez += 1234;
    }
}

Turns out there are 8 search hits! (6 grouped together on top, 2 more on bottom) So we could guess it spawns several different paths to call Execute. Now I'm curious, so let's find them.

Analyzing the generated code

Roslyn Source Generator is here to stay in DOTS. The assembly code of that job is generated from C# generated code combined with your code thanks to partial, so it make sense if we take a look at what Roslyn generated first... just the Execute part. (There are more code generated for the AddCounterJob, such as letting you .ScheduleParallel() to it.)

    InternalCompilerQueryAndHandleData.TypeHandle __TypeHandle;
    [global::System.Runtime.CompilerServices.CompilerGenerated]
    public void Execute(in global::Unity.Entities.ArchetypeChunk chunk, int chunkIndexInQuery, bool useEnabledMask, in global::Unity.Burst.Intrinsics.v128 chunkEnabledMask)
    {
        var xyzArrayIntPtr = Unity.Entities.Internal.InternalCompilerInterface.UnsafeGetChunkNativeArrayIntPtr<global::JustCounterComponent>(chunk, ref __TypeHandle.__JustCounterComponent_RW_ComponentTypeHandle);
        int chunkEntityCount = chunk.Count;
        int matchingEntityCount = 0;
        
        if (!useEnabledMask)
        {
            for(int entityIndexInChunk = 0; entityIndexInChunk < chunkEntityCount; ++entityIndexInChunk)
            {
                ref var xyzArrayIntPtrRef = ref Unity.Entities.Internal.InternalCompilerInterface.UnsafeGetRefToNativeArrayPtrElement<global::JustCounterComponent>(xyzArrayIntPtr, entityIndexInChunk);
                Execute(ref xyzArrayIntPtrRef);
                matchingEntityCount++;
            }
        }
        else
        {
            int edgeCount = global::Unity.Mathematics.math.countbits(chunkEnabledMask.ULong0 ^ (chunkEnabledMask.ULong0 << 1)) + global::Unity.Mathematics.math.countbits(chunkEnabledMask.ULong1 ^ (chunkEnabledMask.ULong1 << 1)) - 1;
            bool useRanges = edgeCount <= 4;
            if (useRanges)
            {
                int entityIndexInChunk = 0;
                int chunkEndIndex = 0;
                
                while (global::Unity.Entities.Internal.InternalCompilerInterface.UnsafeTryGetNextEnabledBitRange(chunkEnabledMask, chunkEndIndex, out entityIndexInChunk, out chunkEndIndex))
                {
                    while (entityIndexInChunk < chunkEndIndex)
                    {
                        ref var xyzArrayIntPtrRef = ref Unity.Entities.Internal.InternalCompilerInterface.UnsafeGetRefToNativeArrayPtrElement<global::JustCounterComponent>(xyzArrayIntPtr, entityIndexInChunk);
                        Execute(ref xyzArrayIntPtrRef);
                        entityIndexInChunk++;
                        matchingEntityCount++;
                    }
                }
            }
            else
            {
                ulong mask64 = chunkEnabledMask.ULong0;
                int count = global::Unity.Mathematics.math.min(64, chunkEntityCount);
                for (int entityIndexInChunk = 0; entityIndexInChunk < count; ++entityIndexInChunk)
                {
                    if ((mask64 & 1) != 0)
                    {
                        ref var xyzArrayIntPtrRef = ref Unity.Entities.Internal.InternalCompilerInterface.UnsafeGetRefToNativeArrayPtrElement<global::JustCounterComponent>(xyzArrayIntPtr, entityIndexInChunk);
                        Execute(ref xyzArrayIntPtrRef);
                        matchingEntityCount++;
                    }
                    mask64 >>= 1;
                }
                mask64 = chunkEnabledMask.ULong1;
                for (int entityIndexInChunk = 64; entityIndexInChunk < chunkEntityCount; ++entityIndexInChunk)
                {
                    if ((mask64 & 1) != 0)
                    {
                        ref var xyzArrayIntPtrRef = ref Unity.Entities.Internal.InternalCompilerInterface.UnsafeGetRefToNativeArrayPtrElement<global::JustCounterComponent>(xyzArrayIntPtr, entityIndexInChunk);
                        Execute(ref xyzArrayIntPtrRef);
                        matchingEntityCount++;
                    }
                    mask64 >>= 1;
                }
            }
        }
    }

Quite a lot of the "first-class support" of enableable components are in the generated code rather than in Entities library! The enable bit mask came from library, but how it decides to call Execute for each entity or not is right here.

It make a lot of sense though, because the enable is attached to one component, the decision to perform Execute or not will dynamically change depending on what components you are asking on the query. You could say this feature is only possible after Unity managed to get Roslyn Source Generator working.

I have intentionally make the incoming parameter named xyz so you could see clearer that it is being referenced in the generated code here.

The gist of this code is that no matter you actually use enableable components or not, the generated code doesn't care and use one central Execute signature that accepts useEnabledMask and chunkEnabledMask (128-bit mask where 1 represent enabled entity). Therefore that first if to check programmatically whether you use the feature or not is mandatory.

If enableable feature is not used

if (!useEnabledMask)
{
    for(int entityIndexInChunk = 0; entityIndexInChunk < chunkEntityCount; ++entityIndexInChunk)
    {
        ref var xyzArrayIntPtrRef = ref Unity.Entities.Internal.InternalCompilerInterface.UnsafeGetRefToNativeArrayPtrElement<global::JustCounterComponent>(xyzArrayIntPtr, entityIndexInChunk);
        Execute(ref xyzArrayIntPtrRef);
        matchingEntityCount++;
    }
}

You can imagine useEnabledMask would be false in this case when Unity schedules this job, and use only the thin part of that if, because the component is just IComponentData without the IEnableableComponent.

It is a simple for loop per entity. Each entity, it calls the real Execute with just 1 parameter that you wrote thanks to partial connecting this generated code with your code. This is where assembly code would reach the number 1234. I don't know why they keep track of matchingEntityCount. Maybe there is a magic assertion somewhere or it causes some good things in the assembly?

If enableable feature is used

That bool useRanges = edgeCount <= 4; is interesting, and if you are like me the code smells like it is challenging me to get useRanges to be true so I get to enter a nicer looking routine with nested while loops.

The edgeCount works on 64 bit + 64 bit of the 128 bit half. Each half, it XOR with itself that is shifted left by one bit, counting how many 1 in the XOR result. Effectively it is checking how often consecutive bits transitioned (the "edge") between 0 and 1. If bit pattern is 111111110111110000, the shift-and-XOR-self result will have three 1 at each transition point. edgeCount is 4 because it transitioned 4 times. As for "range", this pattern has 2 ranges. You look at each consecutive 1s as a range.

Only if it detects that it transitioned no more than 4 times per chunk (effectively max 3 ranges per chunk in most cases), you get to the "use ranges" mode.

With while loop : "Use ranges" mode

int entityIndexInChunk = 0;
int chunkEndIndex = 0;

while (global::Unity.Entities.Internal.InternalCompilerInterface.UnsafeTryGetNextEnabledBitRange(chunkEnabledMask, chunkEndIndex, out entityIndexInChunk, out chunkEndIndex))
{
    while (entityIndexInChunk < chunkEndIndex)
    {
        ref var xyzArrayIntPtrRef = ref Unity.Entities.Internal.InternalCompilerInterface.UnsafeGetRefToNativeArrayPtrElement<global::JustCounterComponent>(xyzArrayIntPtr, entityIndexInChunk);
        Execute(ref xyzArrayIntPtrRef);
        entityIndexInChunk++;
        matchingEntityCount++;
    }
}

Basically this mode hopes that the inner while can work on consecutive entities that are all enabled. When it finally hits a disabled entity, it goes to outer while and UnsafeTryGetNextEnabledBitRange (a very burstable function) jumps over all the disabled entities to start the inner while again at the next clump of enabled entities. Each clump of enabled entities is probably what they called a "range".

I can imagine now that this is the likely mode to get used if I disable just 1 or 2 entities in an entire chunk. For example if 1 in the mask meant enabled, then if I disabled just a few entities it would look like this 1111111011110111111111, and therefore this code would have 3 "ranges" to work on. Note that the outer while is capable of jumping over many 0, so even if I disabled a lot of entities, if they are consecutive, this mode would still get used. (e.g. 1111000000000011110111111 this is still 3 ranges.)

Remember that the point of doing data-oriented is that the data is lining up linearly per component and the cache is nice. A big long "range" of enabled components preserves this goodness.

With for loop + if

If edgeCount prediction says ditch the range mode and just check each entity individually, it checks each bit one by one whether it is a 1 or not (enabled) and Execute if it is.

It needs to work two halfs : 64 bits + 64 bits, and of course stop early if chunk contains less than 64 entities, or more than 64 but less than 128 entities.

ulong mask64 = chunkEnabledMask.ULong0;
int count = global::Unity.Mathematics.math.min(64, chunkEntityCount);
for (int entityIndexInChunk = 0; entityIndexInChunk < count; ++entityIndexInChunk)
{
    if ((mask64 & 1) != 0)
    {
        ref var xyzArrayIntPtrRef = ref Unity.Entities.Internal.InternalCompilerInterface.UnsafeGetRefToNativeArrayPtrElement<global::JustCounterComponent>(xyzArrayIntPtr, entityIndexInChunk);
        Execute(ref xyzArrayIntPtrRef);
        matchingEntityCount++;
    }
    mask64 >>= 1;
}
mask64 = chunkEnabledMask.ULong1;
for (int entityIndexInChunk = 64; entityIndexInChunk < chunkEntityCount; ++entityIndexInChunk)
{
    if ((mask64 & 1) != 0)
    {
        ref var xyzArrayIntPtrRef = ref Unity.Entities.Internal.InternalCompilerInterface.UnsafeGetRefToNativeArrayPtrElement<global::JustCounterComponent>(xyzArrayIntPtr, entityIndexInChunk);
        Execute(ref xyzArrayIntPtrRef);
        matchingEntityCount++;
    }
    mask64 >>= 1;
}

Because this feature is per-entity...

The source generator of job is able to service you the if else should this entity be executed perfectly, because job also works entity by entity. Codegen could put code in the other side of partial before arriving at your code in Execute.

In IJobChunk though it naturally require your manual effort. It starts at archetype chunk level and it already landed in your code, where source generator can no longer perform any more hacks for you. Instead, the API design just give you a DIY kit of the mask, and helper method for you to apply on your own. See details in the official documentation.

About write access

The equivalent hack of having one bool field in a component and then if on that bool to check if it is enabled, the trick before we have enableable component, to enable / disable the component you would need a write access on that component to edit the bool. Therefore any job that need to only read this component will need to wait for the one that could write.

It is the same with official enableable component. If you want to flip the enable/disable status in-job you need a write permission on that component, and it'll affect scheduling as expected.

But since the bool that existed in the hack is now hidden and built-in as a 128-bit mask instead (and they provided efficient code that would flip one bit in this long mask as good as you flipping one bool yourself), you can no longer just add that component as a part of query and just enabledFlag = false/true.

If main thread, you can use EntityManager, or use EnabledRefRO<T> and EnabledRefRW<T> as a part of idiomatic foreach (SystemAPI.Query).

The dedicated method to do that from job is available in ComponentLookup<T>. And passing the lookup into the job will properly add write dependency. Here are relevant ones.

IsComponentEnabled(Entity entity) : bool
IsComponentEnabled(SystemHandle systemHandle) : bool
SetComponentEnabled(SystemHandle systemHandle, bool value) : void
SetComponentEnabled(Entity entity, bool value) : void
GetEnabledRefRW<T2>(Entity entity) : EnabledRefRW<T2>
GetComponentEnabledRefRWOptional<T2>(Entity entity) : EnabledRefRW<T2>
GetEnabledRefRO<T2>(Entity entity) : EnabledRefRO<T2>
GetComponentEnabledRefROOptional<T2>(Entity entity) : EnabledRefRO<T2>

EntityCommandBuffer and its parallel version can also work on enabling / disabling the component from job, but scheduled for later.

// Standard
SetComponentEnabled<T>(Entity e, bool value) : void
SetComponentEnabled(Entity e, ComponentType componentType, bool value) : void

// ParallelWriter
SetComponentEnabled<T>(int sortKey, Entity e, bool value) : void
SetComponentEnabled(int sortKey, Entity e, ComponentType componentType, bool value) : void

Lastly if your job is iterating by ArchetypeChunk, there are extensive functions to work with enabled status. Normal ones that takes in entity index in chunk to flip one bit. Advanced ones that enable/disable the entire chunk (ones with ForAll suffix), or even get just the bits and mask which I can't even think of real use case of.

IsComponentEnabled<T>(ref ComponentTypeHandle<T> typeHandle, int entityIndexInChunk) : bool
IsComponentEnabled<T>(ref BufferTypeHandle<T> bufferTypeHandle, int entityIndexInChunk) : bool
IsComponentEnabled(ref DynamicComponentTypeHandle typeHandle, int entityIndexInChunk) : bool

SetComponentEnabled<T>(ref ComponentTypeHandle<T> typeHandle, int entityIndexInChunk, bool value) : void
SetComponentEnabled<T>(ref BufferTypeHandle<T> bufferTypeHandle, int entityIndexInChunk, bool value) : void
SetComponentEnabled(ref DynamicComponentTypeHandle typeHandle, int entityIndexInChunk, bool value) : void

SetComponentEnabledForAll<T>(ref ComponentTypeHandle<T> typeHandle, bool value) : void
SetComponentEnabledForAll<T>(ref BufferTypeHandle<T> bufferTypeHandle, bool value) : void
SetComponentEnabledForAll(ref DynamicComponentTypeHandle typeHandle, bool value) : void

GetEnableableBits(ref DynamicComponentTypeHandle handle) : v128
GetEnabledMask<T>(ref ComponentTypeHandle<T> typeHandle) : EnabledMask

A limit of 128 entities per chunk

That mask having "chunk" in the name being 128 bits meant that we could only flag up to 128 entities as enabled or disabled per chunk.

The internal ChunkIterationUtility.cs has GetEnabledMask that creates this mask for one component of a chunk we could take a look. (And wow, a lot of care for creating just this 128 bit mask fast!)  And sure enough there are hard-coded 128 around here. If you follow the code, you would eventually reach TypeManager.cs explicitly defining public const int MaximumChunkCapacity = 128; so I think that's it. Chunk right now has 2 hard limits : 16 KiB size and max 128 entities.

You can see this fact in the Archetypes debugger. An archetype of just 16 B each should be able to fit 1000 entities per chunk before the advent of enableable and the mask feature. Now it is capped to 128 entities. You could also say an archetype has "optimal size" of ~125 B where you get your full worth of 128 entities limit.

Is this worrying? (You might fear that for every 128 entities of single component data iteration, cache would need to jump to the next chunk's native array, instead of once every ~1000 entities) I think no. I have code some simple application with DOTS and with many kind of components added up together, it could approach that 125 B number fast. I think they have sufficiently looked at actual DOTS application for average archetype size before deciding on this 128 bit mask thing.

But you should not optimize for enableable

We now know if you disable just a few entities here and there (to be precise, disabled 4 or less entities in each chunk) OR you can disable a lot of consecutive entities in a chunk, it would fall into a good pattern with consecutive data while iterating.

But having to keep in mind which chunk you are working on and whether you have hit the 4 quota or not (more than 4 if you use more than 1 chunk for that archetype, now you don't even know what is the quota!), or whether this entity is next to that entity or not, I think is not worth thinking about. Technical details of deleting an entity in the middle of chunk will also just pick the last one to fill the hole, if that entity is currently disabled, you will create an "edge" in the mask as well.

Unity refined Entities API to let you focus on what mattered already, better not to bring those back. Just enable / disable stuff at will and be happy that it is likely very fast and all burstable. And remember that the point of enableable components are that the enable / disable patterns could be chaotic and frequent, otherwise you would rather slap on a tag component to kick it to a different archetype with a structural change.

(In the end, the benefit of this article is just so I'm no longer curious so thats good!)

Hello, it's been quite some time since the last update. Because there is no comment box in this blog, I'm not sure if there is an audience I'm saying "hello" to right now. This blog was generic Unity blog until I got into Data-Oriented Technology Stack (DOTS) when it just came out many years ago with very wacky API compared to now, then it got substantially high amount of DOTS article, that I thought maybe there are now someone out there who remembers this blog as "that khaki DOTS blog" or something along that line.

While I was away, pandemic came and go, Unity had leadership drama, DOTS reached release status, and AI coding assistant has becoming pretty useful, went through 3 generations of cats, all my friends get married and have kids... it had been that long.

Before diving into what I've been up to lately this is the TLDR : I'm coming back to catch up with current version of DOTS. And I'm going to write on this blog as my tool for self learning like I used to do years ago. When I type things along the way I found I could learn faster, then I got to left some digested knowledge for someone else too.

I'm also looking to delete DOTS articles containing deprecated stuff, which I suspect would be over 80% of them. I'm going to make this blog clean and "safe" for future generations of DOTS programmers to not see any unpleasant things that Unity DOTS team (thanks for your hard work...) 'trialed' and found out ther are the 'error'. Any search hit into this blog I want them to be immediately trustable for Entities 1.0+. So I don't want to mention what got replaced by what here because I don't want those search hits. If you used previous Entities version, this page is excellent to learn what's going away and is replaced by what.

This process would take quite a lot of time, maybe I'd rather delete everything with DOTS tag and write all of them from scratch.

For typical readers you can look forward to some new DOTS articles coming out as I re-learn it. Next up is just some '5argon lore' which I guess you could read to waste some time.

More about myself along those missing years

Learning DOTS while API rapidly fluctuating and keep destroying my project was tiring but I did not get tired of DOTS and quit, which some readers might assumed. I'm entertained by its absurd technicality and what it wanted to achieve by doing so at all costs. No matter what Unity as a company and management went through, I always wanted DOTS skillset in my tool belt.

When it was early pandemic I simply got a full stack web dev job in financial business (generally pays well, especially compared to 'free' DOTS research + personal little passion game I was doing) and job is extremely hard to find at that time so it is stupid to let that go and say you can't buy me out of passion with money. It is also a remote job with minimal on-site requirement, and I get to learn TypeScript, React, Go, Next.. the typical meta workhorse set to make a webapp and make money.

In fact you can if it is enough money (haha) and in no time I was able to go wander in Villa Market, a place full of imported goods, and was able to buy some mid shelf alcohol  like Campari and Beefeater without heavily pondering about my life savings. I was able to iterate on my baking and cooking repeatedly wasting ingredients on failures after failures without worry. I could always grab any bakery and souvenirs I passed by without any thought and most noticed that somehow I looked like a much nicer person than when I was working on my game. And I was able to purchased a robot vacuum and pressure washer for my parent's house.

I could as well use money to get more productive and therefore earning more money with them in a loop, such as able to upgrade my 2015 Macbook all the way to M2, paid subscription to Copilot, or just able to order good coffee when I work at cafe at day time. It's not so different from gameplay loop in games such as Monster Hunter or Cookie Clicker where you could climb up to harder targets and farm more valuable resources. It sounded obvious, but this approach is impossible when I was working on my games and DOTS research out of passion, you know? I just can't afford to upgrade my tool of trades along the way. Getting this job is quite literally life-changing, though it limits things I could do with my upgrades, which is to work more on this job.

Along the way I'm farming money, my game surely stagnates and even got removed from Google Play Store because I forgot to check mail and press some comply button. I'm always looking to eventually request to reduce work and come back to DOTS, Unity, my Asset Store assets, and my game. Coming back from exchanging money for stuff, to making stuff I could call my own. But unfortunately in early phase of that product I can't really stop. I thought it'd be like 1 or 2 years before it gets less busy, but turns out it took 3~4 years.

This year and this month is finally that time I'm looking for. So here I am. Thanks for reading. Cheers!

Ps. Thanks to this remote job I was able to move back from capital to a more comfy hometown with my parents there. Completely unrelated to this blog but I also got into a new Arkham Horror LCG hobby and was able to connect with my highschool friends to form a regular play group. Since I already like this game, I started a static info site http://arkham-starter.com/ project, a very good excuse to learn Svelte, and as some stress relief from actual work. I'm looking forward to apply this Svelte knowledge to remake my game's homepage when I get to that point.

As a package publisher, supporting lowest possible version is ideal for covering your user bases and therefore increase revenue. But in exchange, using version too low will results in many difficult problems.

It becomes a balancing act whether you think the revenue of supporting lower version worth it vs. bumping the lowest version up.

This article will highlight them all from personal experience, having maintained Introloop, Native Audio, and Tiny Ambience. Introloop especially, published its first version in Unity 5. (Now that takes me back! It really begins in Unity 4 or something while I was working on a game called So Many Me with an another company.)

TLDR

Develop all your UPM Asset Store packages on 2019.4 LTS.

Obligations to go back and check

When you say your package works with Unity 5, you must actually go there and check that it works. If you develop in a single project, this may mean you "lives" in Unity 5 forever while developing it to ensure support.

Then when you are about to release, you upgrade sequentially to 2018 LTS, 2019 LTS, 2020 LTS, and so on. Then check on each version.

Upgrade is usually a success, not so with downgrades. After sequentially checking all future versions, you don't commit the change to version control and come back to Unity 5 to develop new features. You will cry having seen better Unity in the future and then having to come back to jurassic period to work on your stuff.

Always choose one of LTS versions

Back then Unity doesn't have the LTS version that guarantee bug fixes for several years. Now that Unity has it, game developers (especially big companies) are very likely to choose these LTS versions for their game instead of any mid-year versions.

Now it is obvious the lowest support should be one of these LTS versions to support as many big company customers as possible. It will make our lives easier too when these versions would stay for a long time.

Choose only versions in Unity Hub

Also, Unity Hub is a thing now. The hub serve as an another filter that prevents average users from seeing any other obscure versions. As a package publisher, we can play along and pretend that only these versions exists to simplify development.

In this image, 2017 LTS does not exist anymore in the hub. Now your choices are just one of 2018.4 LTS, 2019.4 LTS, 2020.3 LTS.

Why supporting 2017 is a bad idea

2018.3 has a great world-shattering update that was Prefab Workflow. I remembered along with that, asset serialization changed a lot that make downgrading to 2017 impossible.

It is wise that your support starts after that "new world" so you don't have to deal with users that uses assets from jurassic era. (That is, just ignore 2017 and lower.)

2017 does not even have Assembly Definition asset .asmdef. That has a lot of features that paved way to UPM support. This also affects all your code, since internal doesn't work anymore when it is one big assembly. [InternalsVisibleTo] is unusable to create good test assembly. And you require a magic Editor folder! All these will make users working on 2020 LTS vomit when upgraded to that version.

Why supporting 2018 is a bad idea

Whoa! 2018 still exists in Unity Hub! Why would you cut off the revenue like this?

This decision sounds familiar to dealing with texture format. You are worrying about users with old phones that couldn't download your game anymore if you decided to go modern. I abandoned those users and getting much nicer sleep by the way. So it is up to you!

Back to the topic. 2018 is behind one more important world-shattering update for package publisher that is UPM publishing, the next step after .asmdef.

Missing Package Manifest

User now install Asset Store stuff via UPM. While that Package Manager panel will import (pour in) the asset into your Assets folder anyway if those packages aren't actually UPM, if your package are UPM-supported, your users will be delighted that your package stays neatly in Packages section instead if actually in the game.

This can be confirmed easily by going to the Package Manifest page (the package.json) and click the upper left corner, the lowest LTS that this page is available is 2019.4.

If you could use package.json, it will affects :

• How you deliver your user an offline documentation. No more random readme file when there is a standard where to put your stuff.
• How to deliver your user samples. Problem was that samples are imported into the game along with the package, then user have to remove them because they adds up to import time if they contains scripts, images, or audio. (Even when not actually used in game.) UPM comes with sample importing button with a new standard how to do it. This came in 2019.1.
• Your online documentation will suffer from "if you use 2019/2018" hell because how user install, consult documentations, etc. is different from 2018. You need to keep saying this to accommodate all users.

Missing Dependencies

Dependencies can be automatically installed via dependencies in the manifest, so they don't appear as game dependencies.

For example if my package needs Addressables, but my user's game didn't need it, my user's game will ended up having Addressables as a result of installing my package, but Addressables aren't listed on the game.

Removing my package will instantly also remove Addressables from the game.

(You can't use range syntax like ^, only a fixed semantic version.)

Missing ASMDEF features : Version Defines

Even asmdef features are affected. The most impactful would be version defines. This make a define appear or disappear based on other resources. It can turn your package into a flex god, offering more extra features as user installed other Unity packages!

Bottom line : Let's together skip 2018 LTS revenue! Time will heal everything and not too long to wait, this version will fade away.

What about 2019.4 LTS then?

C# 8.0 is not available

This might be small, but my favorite is switch expression. It reduces bugs in the code when switch is forced to return the same kind of values for all "arms" (not "cases").

Another one is private static method. (No private keyword, just static but defined inside a method.) It completely disables variable encapsulation, making your function 100% pure. You can even use the same argument name as some variable names from an outer scope. I found that 90% of my nested functions in the method actually wants to be static.

If you want to maximize reach with supporting 2019.4, say goodbye to C# 8.0 and only enjoy those in your own games.

Missing new serialized array editor

2020.3 came with cleaner serialized array editor drawer that has rearrange handles, along with + and - buttons!

If you are going to stay on 2019.4, it maybe better to temporarily come to 2020.3 when you are making screenshots for your documentation so your array are rendered better, if your plugin involves working with serialized array.

Package Manager is a bit unpolished

Here is how it looks like in 2019.4 LTS :

Then look at how glorious it is in 2020.3 LTS :

Luckily, both has samples importing buttons. So your documentation teaching user how to use samples works on either. I think differences are mostly visual.

One gotcha on the "In Project" viewing mode is this dropdown saying "Unity Technologies".

This string is pulled from package.json : author > name. Make sure to have this consistent across all your products so they are grouped in the same drop down.

Initially I have packages developed on my own ("5argon") for fun, and also Asset Store commercial packages I want to release as "Exceed7 Experiments". Technically the name should be different like that, but I disliked how my packages are fragmented to different dropdown. Now I consistently use "Exceed7 Experiments" for everything, personal or commercial. (I believe email and url can vary?)

The new publisher portal

...requires submitting new packages from 2019.4 or higher. Only updates are allowed to go as low as 2018.4.

And now the store itself will also follow LTS version. Store will not accept packages using LTS version that had already fallen off the support. More info here.

If you use lower than 2019 then your day is numbered!

2019.4 for life?

Other than mentioned, personally I think 2019.4 LTS is the best home for all package developers for time to come. Unity finished modernizing packages with asmdef and package.json right here, missing just some Package Manager upgrades. It will be the new Unity 5. All my packages will be staying in 2019.4 LTS for sure!

Note that due to "store following the LTS" policy, this would soon move to 2020.4 LTS in the next year as 2019.4 fell off.

Providing extra features on new versions

You may want to commit to provide extra features on newer versions, which translated to having to maintain #if in your code. For example though lowest version is 2019, if 2020 is used, it gives you a bit more features but not critical to usage.

This goes beyond Unity version now that Version Defines based on package is available. Unity Timeline package version 1.5.2 for example, has a lot of editor functions added that it is possible to script C# to pop open a Timeline tab. I want to have a cool button that use these functions.

However, Unity 2019.4 that I decided to stay on comes with Timeline version 1.2.18 verified.

In my package.json, I can either :

• Say that it needs Timeline 1.5.2 as a dependency, then I can be free of preprocessor directives and no Version Defines.
• Say nothing about Timeline dependency or explicitly states 1.2.18 which comes with Unity 2019.4, then use Version Defines to check and enable an extra define. This is then used to render that cool button in my editor code, otherwise the button is greyed out or invisible.

The preprocessors are notorious for wrecking with refactors, keep in mind. You no longer have a peace of mind using tool like Rider to refactor things as it doesn't go into deactivated section of the code. Resulting in surprise error report from users when you didn't go check on all versions which would trigger defines differently after any refactors. (i.e. Refactoring is now a potentially breaking change until you actually check with all supported versions.)

Publishing gotchas

Here are extra tips related to Unity Asset Store Tools and the new Unity Publisher Portal.

Checkbox of doom (?)

The 3. checkbox seems to promise compatibility with GUID reference in your .asmdef. But according to this forum post, I think it is best that you don't check this box for now, for many reasons. (lol)

Marketing image dimensions

The new uploader does not reveal required dimension of marketing images nor how many would be needed until you drag something onto it. Therefore, I will show you the resulting dialog after dragging right now.

Best to match the dimension to these. When you check the bullet, only Social media image requires that you don't put any text or logo on it.

Screenshots dimension

This one is a bit trickier, since it says "min width 1200 px". So what size should we use?

The answer is 1950 * 1300. The reason being that these images are shown after Cover Image in the previous section in the carousel UI. If they are of different dimension than this, (grey) letterbox on top and bottom would be added and the image is centered vertically.

How the Social Image looks like as ogimage

When people share the Asset Store link via Facebook or Twitter, the Social Image (1200 * 630) (that they told you not to add any text) would be used as ogimage in the "card".

Here is the original inside image editor program.

Here are the results :

As far as I tested, that dimension translates quite well!

Page indicator on screenshots

In that 1950 * 1300 pixels, Unity will put page indicator near the bottom edge (Including the Cover Image). It is best that you don't fill important graphics to the brim especially if they are text. In my product here, I pad only the bottom edge up a bit.

The padding from the bottom edge of your graphic to the bottom edge of that page indicator is 35 pixels. The height of that page indicator is 48 pixels. Counting padding 2 times plus the height, total padding should be 35 + 48 + 35 = 118 pixels to get padding similar to my example.

Folded technical details

Previously, Asset Store not only require us to write HTML tags to style things and also it only got one description area. Now they have added "Technical details" section you can add more texts.

To keep in mind that this section is folded by default. So make sure to put all the important ones in the "Description", like your contact details.

Publishing queue

If your package is new, it takes a month to be reviewed. (As opposed to an update which is faster.) The new Publisher Portal also show where you are in the queue, you can edit the package without losing queue position. However, I had seen my queue number goes up, so don't take this number too seriously.

This is something I always forget when designing a new API that I want to be compatible with UnityEvent target serialization. I would like to end that, by writing this article so I could come back and read instead of blindly trial-and-error again to no avail.

What is UnityEvent serialization?

Everyone knows that declaring public will "expose the variable".

More correct term is that it mark that field for serialization. Serialization means the data could be remembered in the asset or in the scene instead of starting from zero. It is the data you can input to that exposed slot that get saved.

Then advanced Unity users know that [SerializeField] property is a way to also allows other access modifier not public to be serialized.

Finally even more advanced Unity user knows that UnityEvent is equivalent to C# Action but more awesome because it could be serialized! In other words, you get a nice editor that allows assigning invoke targets, which stays there nicely.

Despite an editor feature this nice available, I still see tons of Unity developers intentionally not using Button's nice on click event box that appears in the editor and instead assign everything by code even though they are only one-time assignment. A month or so later, it is impossible to trace which button do what because they are all empty in the editor, and who know which code assign or replace the listener at which moment!

Main topics here is that what would be the criteria to make it appear in the dropdown? Surely, these aren't everything that Camera has to offer.

What does the serialization looks like?

Notice that it "remember" the target with assembly-qualified class name. This has some concerns :

• If you change the class name will everything breaks?
• If you move the class to different .asmdef will it also breaks?
• Remembered argument is also assembly qualified full name. If Unity is evil and change assembly name of UnityEngine then would it breaks the universe?
• If you refactor target method's name, I think it will breaks?

Argument editor is more awesome than you think

You see the check box above for booleans. It also supports number box and string box. But less known feature (probably) is that it also supports an asset picker!

This is really useful to not have little pieces of audio playing code bits littering all over. Also it is extremely good with prefab workflow. It shows the blue override bar correctly. The prefab variant can add more entries, keep inheriting entries from root prefab, etc. It is critical with the new Unity Localization package which it uses event targeting extensively, all my texts are a variant of one root text prefab! But it is not our interest right now.

The serialization :

You also notice here that it is limited to only 5 types : object, int, float, string, bool. But the object type is so flexible and is my favorite. You should abuse it!

When will things break

See that Assembly-CSharp over there? I thought I could instantly screw up the serialization simply by moving the ConnectionTarget to different assembly.

But turns out it is still fine.

Seems like the priority goes to the class name first and assembly is there to tie-break. If I rename the class...

Ok finally it breaks!

But you can still save its life. By doing things in this scene and save it, it will not try to nullify invalid serialization. Therefore when you realized you broken the link as far as the last month, it could still be saved somehow as old serialization is still there.

I could remove the z in the class name, and the serialization could come back to life.

In a way, this non-GUID serialization is both blessing and a curse. Sometimes it makes you unable to refactor. But at the same time it allows certain flexibility... once in my project, I got into deep trouble and break everything in the project while refactoring!! I fixed the problem by scanning all YAML files and perform string replace of these class names and an entire project is saved. Thank god.

Dynamic events

It means that normally UnityEvent requires an invoker to specify nothing, the argument is fixed by whatever serialized.

Therefore dynamic means that the argument is specified by the invoker instead. Unity supports this by providing you UnityEvent<T>, UnityEvent<T1,T2>, .. and so on. Up to 4 dynamic parameters. (Note that static one only supports 1 argument that you can type in Unity Inspector.)

But the catch is Unity can't serialize generic classes, it must be a solid class known ahead of time. How to make it "solid" is like this. It could be private just fine too but remember to put on that [Serializable] (Unlike fields, a public class is not automatically serializable.)

Conveniently, Unity shows eligible dynamic event target up top. Selecting this no longer show AudioClip selection box, because invoker will supply it.

You can still ignore the dynamic event and go back to use the static one as well.

Only public works (??)

This is the first criteria to get it on the dropdown. Supposed we have 3 versions like this :

Only public works. There is no magic attribute like [SerializeMethod] to paste to make it work with internal. This is quite sad for C# freaks who like an extra tidy code.

Only the public one appears...

Can we hack it?

Where's the fun in playing fair, right? What if I just go ahead and edit the serialization like this. If you love serialization by name so much, then get wrecked.

Turns out it works (lmao), but do you want to sacrifice usability in Unity editor just to call internal or private methods?

It even lights up in JetBrains Rider!

You can also "hack" in the editor by entering debug mode. To be honest the "debug" editor is kinda nice!

I am designing an Asset Store package however, so it is unacceptable that user must hack like this in order to make my component compatible with UnityEvent. I have no choice but to play with public rule.

Other than that, you decide for yourself is the code hygiene of not using public and still be able to call it from UnityEvent important to you or not.

Only 1 static argument allowed

The static event can only call 1 argument methods. You can kinda confirm this by looking at the internal fields of event : the arguments may have an s, but it stands for holding 5 different type of arguments in 1 argument.

What if we have mismatched parameters than required

This event has 2 dynamic arguments AudioClip and float. I want to try targeting the one with only AudioClip.

It does not work. Unity doesn't know how to ignore extra arguments.

What about less argument? Call this method but with the dynamic event with only one AudioClip.

Nope, nothing appears. Just in case, the perfectly matched one of course works.

What about optional arguments?

No! It is not that smart! You better think the optional argument as a real argument.

But this will place heavy restriction to package API design as well, as when you finally get a lot of smart optional arguments and overload resolution planned to work beautifully (e.g. just one Play method name that works in many ways), then you want to make those compatible with UnityEvent suddenly there is a wrench throw in.

A way to get out is to make a new entry point just for the UnityEvent, but you have to invent a new name which may get ugly. (e.g. suspiciously wordy PlayAudio in addition to Play, just so UnityEvent has something to connect to.) I do this in my package because it can't be helped.

Can we hack it?

It has just AudioClip, but method name is edited to the one that also requires float (or optional float)

It does not work. (Entering Play Mode and invoke will not do anything when "Missing", no error also.)

If there is a return value?

In my Asset Store package, I want the play to also return a value. This could be used to stop the already played audio.

Unfortunately, having non void return value disqualifies everything. Including the public one.

Same as dynamic version :

Can we hack it?

Perform the same hack by directly edit the method name. Note that the argument is perfectly compatible, exactly 1 AudioClip.

Whoops, I was caught this time!

Though, we now additionally know that it uses System.Delegate.CreateDelegate underneath, which is standard C# rather than a Unity-thing. So if we know how that works, then we know what could and could not be hacked. It could be assumed now that Unity engine coded such that it binds to void return value of the target class, but there is no criteria on access modifier so the hack was successful.

Interestingly CreateDelegate overloads has firstArgument criteria, so maybe this implies if we hack the 2nd argument it could get through. But I am too tired to try that now.

No interface arguments, but subclass OK

If you made your API to be nicely handling interface of your custom class, then bad news the serializer don't know how to deal with it.

But subclass is OK! This allows the asset picker to pick any subclass from the base class specified in the method's signature. This allows you to use abstract class as well. In this image, AuditoPlayableBase is an abstract class.

In this picture, that public void is just a scapegoat for UnityEvent targeting. It is using a class not interface so Unity know how to serialize the static argument. Moreover it has void return and not AuditoHandle I actually want to use.

The object picker shows all the choices that subclassed from AuditoPlayableBase that aren't abstract anymore. This is a really nice developer experience for the user.

This leads to weird class tree design where an abstract class is there just so Unity could know how to serialize, but the real deal is the interface I want to use everywhere. The best solution maybe to hide the interface behind abstract class, and abstract class may essentially do nothing because the interface had already locked in everything. (lol)

Can call static

I found about this by mistake. Though it make sense that it should be able to, I didn't think Unity would actually let me to do this lol.

This is given all the previous criteria are passed, so must be returning void. It can take arguments just fine, like discussed.

Implications in API design

Because the target's name will be forever serialized in the client's code, you must make damn sure you don't refactor the name to something else. This already applies to all your public code, but breaking people's serialized event target won't trigger compilation error. Scary stuff!

And you have to be more skillfully sidestep everything. Take a look at this :

• The first requirement is that I want the static method Play with complete overload + default argument, so I could type NonpositionalAudio.Play to use it. It has return value too.
• Then I want to make an instance public Play method to service those that wants to use UnityEvent. First I have to sacrifice return type, then also interface is not usable.
• Lastly there is one more Play overload I want to be able to use with events. But if that is named Play, it will cause infinite recursion to itself instead of resolving to the static method. Now I have to name it something else.

And this 5 Play :

Normally the bottom 2 are enough to handle everything I want, but if I want it to be compatible with events, I need 3 more above with no return value. Also I cannot just use default arguments, I need to explicitly add all the combinations. Of course I cannot use interface too. Lastly, I can't name the top 3 Play anymore as it would cause similar problem as before. So, I name them PlayAudio instead.

(Other idea includes PlayFromEvent, to explicitly excuse that there is no return value because it is "for event", but I think that is weirder.)

Seeds Instruments made a pretty interesting 34-key Kalimba called the Pisces!

• https://seedskalimbas.com/
• Seeds Kalimba | Facebook

I wanted a Kalimba to add interesting calming arps when composing game music for long. As soon as I see this arrangement which is currently not many brands are doing, I felt adventurous and wanted to explore. I love when a brand try to pioneer something and there are not much information anywhere else, I wanted to be at the frontier and experiment. Just like how I was messing around with Unity DOTS.

And so with magic of today's e-commerce, it finally appears before me. Let's get the research started.

In this article, I analyze the implication of this 34-key layout what possibilities are opened up. This assumes we will not re-tune the Kalimba to fit the song we want to play. We want the added flexibility of more tines to counter that!

If you wondered why this kind of article appears in a Unity game programming blog like this, I picked up some instruments in lockdown and the diagrams here were made with Unity..! And also just so you know the Kalimba sound is leaning nice into game soundtrack territory. This sonic character could be in calming village music or fantasy forest theme.

This Unity project I quickly whipped up in about an hour can ask all the tines to number itself according to either major or minor scale interval starting from any note and hide unrelated ones, so we could reveal interesting properties visually.

This article requires a bit of music theory knowledge. (How many notes are there and their distances, key, chords, interval, diatonic, chromatic.) This maybe the first article taking the 34-key Kalimba seriously on the net since I can't find anything elsewhere, the 17-key version is so popular it dominates the scene. Therefore, let's start at 17-key.

Recap the 17-key version's arrangement

The popular 17-key version is diatonic centered around major scale. It is literally centered, the root note is on the center tine. So it means either you bring the tuning hammer with you all the time in order to play all songs or you transpose any other song to this key you choose. Note that the hammer can't fix everything since tine length gets more limited on the edge, not only we can't get higher, shorter tines has less decay time as well and require more force to compensate.

It has alternating tines left and right to form a major scale starting from the center tine going left first. Numbers in the picture are note/key agnostic, it is the member of your major key.

For example, in C key Kalimba 1 is C, 6 is A. In music theory, there is no "black" notes since actually we have 12 notes lined up linearly. These 7 notes C D E F G A B C we see as a result of C major scale here looks linear but they aren't, only because of English alphabet tricks your eye but each one is 2 semitones apart, except BC and EF. So 7 notes looping can't be equally spaced, we need 12 notes and 2 kinds of distance : 1 semi + 2 semi. This is maximal evenness. In parallel world, we might have A B C D E F G H I J K L as notes and there is no sharp or flats since those would give the nearby alphabet without exceptions, if the English guys discovered chromatic before diatonic or something.

Easy tonic chords glissando

The alternating tines are probably for ergonomics of distributing notes to both thumbs but that is not all, it allows single thumb 3 notes glissando to form tonic chords perfectly. Tonic chords means not just any chord but they could "work" together to create a song in a given key of music, creating tension and resolve back.

The green arrows are tonic major chords and red arrows are tonic minor chords. You can easily get your : I, ii, iii, IV, V, vi, vii chord of the tuning of your Kalimba with a gentle slide starting from the number that you want and going outwards. It automatically skips notes of an interval too close to the previous one automatically, which that would sound dissonance. To play the popular chord progression I -> IV -> V -> I, just find any number printing on the tines literally saying 1, 4, 5, 1 then slide away.

Piano players know keys close by could be used to form interesting uncommon chords to spice things up. Kalimba made the spice impossible when randomly brushing around. As a result if you left the Kalimba for other not knowing music to mess around, it would still sounds quite pleasant unlike if someone randomly press piano keys.

Also if you want to play ii minor chord, you can do 2 4 6 on the left side, but it also is available on the right side higher up! Talking about extremely lucky coincidence that there are 7 notes so by alternating left and right we get both even and odd numbers in one side. The 17-key arrangement is a very good idea, no wonder why it is popular.

I skipped 7 2 4, the diminished sounding chords, in the image to highlight all available major and minor chords. Of course you can play that for occasional spooky sound.

4-Note Chords

We are even luckier that brushing 4 consecutive tines automatically get us the bluesy sounding seventh chords like 1 3 5 7 one, or 2 4 6 1 one.

• Blue arrows are major seventh chords. Notice that we have 2 "1 3 5 7" position to play.
• Magenta arrows are minor seventh chords. Notice that we only have room to play the seventh version of vi chord, the 6 1 3 5, on the left side since the other one on the right starts late and the "seventh" component fell off the edge...
• We can play dominant seventh chord on the yellow arrow too, which would play G7 in this case.

Of course you can continue to get the rich ninth chord sound, etc.

Range

Notice that the 1 note spans about 2 octaves, then we get a little 2 and 3 over and thats it.

If you play major key song in the same key as Kalimba, the "home" is probably 1 on the left side so you can go both up and down. Depending on song, if it gets emotional it maybe higher than then range that you need to move the "home" down to the center 1. (Which may gets too low to your liking, but thats "Kalimba arrangement" for you.)

Another major scale choice (Mixolydian mode-like)

We can somewhat play the major scale of 5th member of the Kalimba's key too! In the case of C Kalimba, then this is how G major scale would play out. (G is perfect fifth from C.)

"Somewhat" means that one tine will be wrong if you really play Mixolydian of C scale compared to the real G major scale. So please play almost Mixolydian.

That tine is the "7" note. This note is a component of quite important V chord (5 7 1) so keep that in mind, and also iii (5 3 7). The vii (7 2 4) is rarely used, luckily. This note 7 is also used in a melody to lead into 1 so this will impact some songs doing that.

The wrong tine by the way, if you go ahead and play it in place of 7 in the context of G major scale then it is a sharpened 6 (or flattened 7) instead. You can use this fact to play new chords that has sharpened 6 as a component.

Also the flattened 7 wrong note has a name, the subtonic. It also has many uses different from the correct one (leading-tone). I would not consider playing in this position that "wrong".

Note that in harmonica, trying to play G major scale on C harmonica is called the 2nd position or the "cross harp". The blues player play in this position, the reason is because the "wrong" note happen to be exactly what blues want, it feels bluesy. So when playing G major blues song, harmonica finds a C major one and play in this position.

Yet another major scale choice (Lydian mode-like)

Closely related to the perfect fifth above root is the perfect fourth, or in other words going counter clockwise in the Circle of fifths instead. In C Kalimba, the 4th member is F. This is how it looks like if we make the 4 note instead our new home.

If you really go ahead and play Lydian of C as a makeshift F major scale, you will also hit one wrong note in the same reason as the G major scale vs. C major scale but "to the other way". This time the missing note is the 4 note, which is a component of ii (2 4 6), IV (4 6 1), vii (7 2 4). The vii chord is rare so we are lucky, but missing ii or IV chord maybe problematic.

Minor scale play (Aeolian mode)

You can play the relative minor scale of your Kalimba's key for some emotional songs and get the same glissando chord benefit. The home moves to note 6 and if you choose the 6 on the left side as your home then you get a bit higher upper range than the major scale playing.

Let's see if we look at the note 6 as a new 1 for our minor scale, what would it looks like. All tines are correct, naturally!

By shifting the numbers, range are affected. For example there is only 1 instance of 2 4 6 glissando remaining now. Poor II chord! (The II chord switched from vii that was in major scale.)

Playing in Dorian or Phrygian mode for more minor scale choices

Same reasoning as when we want to play 2 more major scales with 1 wrong tine, you can do the same starting from A minor scale we can naturally play and go clockwise and counter clockwise. Therefore it is D (note 2 of C) and E (note 3 of C) minor scale we could also somewhat play with 1 missing note.

Here's how D minor scale on our C major Kalimba looks like. The missing note is 6. (It was 4 in major scale.)

Some observations :

• We have 1 3 5 glissando available to play the home minor chord on both sides.
• We also have 5 7 2 for minor scale version of V chord.
• 3 5 7 is also cool.
• 7 2 4 on both sides are not so useful in most songs.

Here's how E minor scale on our C major Kalimba looks like. The missing note is 2. (It was 7 in major scale.)

Some observations :

• We have 1 3 5 glissando available to play the home minor chord on both sides still but the position moved a bit.
• 5 7 2 no longer possible. (which is probably quite a big deal since it is a V chord)
• 3 5 7 is still possible.
• Now we can do 4 6 1 and 6 1 3 on both sides too.

Compared to major version, because the missing note is not 7, you don't get the leading-tone-to-subtonic benefit.

Recap the 21-key version's arrangement

The extra 4 tines are added for extended bass sound.

They are jammed right in the middle as low 7 5 4 6 tines, so the center is no longer your root note of your key. You can still perform glissando chord trick from new bass notes, for example from the new low 4 6 into the original 1, or the new low 5 7 then onto the original 2.

These are also good idea since now you are able to lay down interesting interval under your melody as a representative of chords in the song.

Here comes the 37-key arrangement

The idea is to make a 2-row Kalimba where the first row is exactly like 17-key version (alternating major scale), then move the 4 extra bass tines of the 21-key out of the way to 2nd layer, then fill the remaining upper tines with a sharpened note of the first layer. (one half step higher)

This is a diagram from Seeds Kalimba Pisces :

Accidentally chromatic

Many call this "chromatic Kalimba" but notice that the upper tines aren't equivalent of black keys on the piano. They may ended up covering all notes chromatically "accidentally" but the upper tines do not care about that, they just want to sharpen the lower one.

First, the upper row 7 5 4 6 are special, they are not sharpened tines but your extra bass notes in the major scale of lower row that are now made "optional", inspired by 21-key design. You reach up for them when needed instead of having them breaking the flow of beautiful alternating 17-keys. These rows aren't adding any chromatic quality from 17-key design that was diatonic.

Now the sharpened tines are the real deal that adds chromaticity (that is a word?). Because playability is still centered around the lower row having major scale ready for you, using these upper tines for accidental notes that music composer added for spice maybe a good idea rather than trying to play in arbitrary keys.

However remember that among 12 notes in one octave, BC and EF are only 1 half step apart unlike the other guys. Therefore the sharpened 7 is 1 and the sharpened 3 is 4 in all major scale. We can see that the upper tines therefore sometimes include duplicated sound of the lower one. The upper tines are really meant for sharpening, not for covering all notes.

Make use of the duplicated sharpened notes

Having 2 more "1" note and "4" note available up there may comes in handy sometimes.

You can perform exact pitch unison with 2 same notes to amplify it, or you can trill the note with both of your thumb for style like some other instruments!

The 1 note is likely to sound good as an interval with the other tines in many situation since it is the root of the key that you are playing, assuming you are playing the same key as the Kalimba's key.

Any interval pair in your key with 1 and 4 is going to give you some more choices. So look out for them.

You can also perform this cool trick, vertical glissando. But you can only do it on 1 -> 7 and 4 -> 3. There are 4 positions you can do this. If you prepare your other thumb to add 6 and 2 respectively, it sounds quite like believable you just brushed with one thumb! Or you can drag diagonally and play other nearby interval as well. Might looks flashy in your Kalimba video..

Bonus high-4 note

Note that the rightmost 4 is not exactly a duplicate since it is on doubly high octave. This give more variation for you to perform unison interval of various instances of 4.

Perhaps more importantly, it extends your range by 1 note in the key of C as if there is one more tine to the right of the rightmost tine, you just move up instead. This is because 3->4 is one of two place where we only need 1 semitone up to get to the next scale tone, lucky!

When playing on minor scale song and you start at 6 (to be your new 1), note 3 (the final lower tine) is the "5" of minor scale. 5th tone of any diatonic scale is the dominant, well documented as very important to the song. Therefore this bonus 4 will give you the "6" of minor scale, the submediant. So when you use the Pisces, you are able to play minor key songs that use this submediant-feel in the composition on high notes, provided that you transpose it to A minor first.

Most Kalimba stops at high 3 (E6 note, if in C tuning). Be warned that this bonus 4 tine is very short and hard, most low quality Kalimba would not sound great but it works on the Pisces, perhaps thanks to unibody metal saddle design.

Arps from bass tines

It moves up the 4 bass tines from 21-key to above. If you want to arp from lower notes, then you cannot just brush your fingers. Instead to play the 4 available triad of your scale degree : 4 5 6 7 (4 6 1, 5 7 2, 6 1 4, 7 2 4) starting from the bass tines, and send off to the higher octave, you follow a pattern like this :

Some observations :

• All chords are one handed from bass tines, but at the moment you hit all 3 notes, the next one will be on the other hand which you continue like the usual 17-key format. This works the same as in 21-key format, if you want to arp several times it would alternate sides.
• Because the 3-note chord is splitted up into upper part and lower part, remember that the 4 and 5 chord will play the upper one 2 times, but 6 and 7 will play the lower one 2 times to not get confused.
• 2-note glissando as a part of chord maybe possible. If you want more challenge you can even do vertical one. (e.g. in 4 6 1, instead of glissando at 4 6, try 6 1 instead.)

Sharpening minor chords into major

Since the upper tines are strictly sharpening the lower one, every time you play minor chord on the lower tines you can change the 2nd note to the upper one to instead get major chord. (But you can't glissando, do an arp instead.) Also the upper one must not be one of the special 4 bass tines.

It will be out of key, but some song use this trick to spice things up. (It sounds emotional in a certain progression, when listener think they get a minor next but instead it is a major.)

Available chords : 2 (right side), 3 (both sides), 6 (both sides). You cannot sharpen the 2 chord on the left side since it collides with the 7 bass tine, that one is not sharpening your note.

Inverse is possible, if you play major chords on the upper tines then you can turn it into a minor. But in your Kalimba's key, it is unlikely that you can play major chord on upper tines. (If you play C# major key on upper tines though this is very possible, explained later.)

Now we have more scales for real!

Remember how we could only play perfect major key of the key of Kalimba and its relative minor key song, but when we push them further then there are tines missing?

Now that we have sharpened tines plus the bass tines, let's see how it turns out!

Mixolydian-like (C major -> G major)

Instead of missing the 7 note now we have one 7 note waiting up there on the right side! Therefore it is now possible to play the G major scale on the middle range, or compose missing chords using that one lifeline we now have. We knew the wrong note was a flattened version of the right one, and luckily the sharpened tine give us that up above.

Note that it is possible to perform 5 on the right side and then diagonal vertical glissando 7 2 to perform 5 7 2, the essential V chord sound needed to finally go back home to I chord. Looks like that 7 will be your buddy when playing in this position!

Also notice that the 4 bass tines covers note 1, 2, 3 of the key on this position. Having deep 1 bass in that position will be very convenient.

Note that the fact that it is weird that we get only one 7 note in an entire board is because of "wrench" than the upper bass tines threw in. We likely get one more 7 if there is no bass tines there.

Lydian-like (C major -> F major)

Recall that we were missing the 4 note. The sharpened tines gives us 4 notes on both sides. This make the 4th of home scale very usable!

Let's look at the chords that were missing :

• VI (4 6 1) has diagonal vertical glissando of 4 1 available on the left and right side, then you just add 6 nearby to get it. The right side is difficult since the upper 4 has short tine.
• Then ii (2 4 6) should be done with alternating thumbs since there are no nearby tines. We get one lucky vertical 2 6 on the bass tine area, if you would like a bassy ii chord.
• Lastly vii (7 2 4) is rarely used anyways.

Once again the 4 bass tines has 1, 2, 3 of the key. Now 1 is even on dead center!

Aeolian (C major -> A minor)

What do we get more if we play relative minor? We get 1 and 2 bass to use. Two 6, two 3.

Dorian-like (C major -> A minor -> D minor)

The 6 note was missing, now we get it on both sides. Unfortunately minor scales will not get the 4 bass tines cover the root note. Instead, we get a 4 and 5 bass tine that maybe useful for going back to the minor home.

Phrygian-like (C major -> A minor -> E minor)

The missing note 2 was filled with one tine, at the same spot as 7 that was filled in our Mixolydian-as-new-major case. Music theory!

Upper tines keys?

Inversely, there are possibilities that we could play some other keys that mainly use the new upper tines so we can instead be glissando up there for a lot and occasionally come down! This way 4 bass tines are likely out of key, but let's explore keys that has many in-key notes on the upper tines.

C major -> C# major (+1 semi major)

Playing one half step of your source key is the shortest way to sharpen all the things. And this works to our purpose!

• Useful chords all on upper tines. Left : vi (6 1 3), I (1 3 5), iii (3 5 7), V (5 7 2). Right : V (5 7 2), vii (7 2 4), ii (2 4 6), vi (6 1 3). We have V and vi on both sides. The home chord I is only on one side's glissando so we will have to pay attention to that.
• Only two 1 notes available, and they are all high pitch. This may force the range to be narrow, you many not be able to play songs that are too dynamic on this position.
• Important to note that if you ignore the 4 bass tines (ok the center one works as a note 3 bass), all upper tines are correct. You just need to remember where are the 1 and center yourself around them.
• Bass notes are limited. You only got low 7 and low 3 at your disposal. May need rearranging to brighter style to fit this.

If you have Seeds Instruments Pisces in C then look for songs in key of C# major. You can comfortably nail about 1.2 octave of this key via the upper tines. Tuning without hammers!

Another important implication : 1 semitone key shift. Some songs shift keys up briefly to be emotional (e.g. Connect, Madoka OP, at the beginning) therefore if you transpose the song to C major (comfortably play on lower tines), then you get an easy shift to C# major by moving to this position on the same Kalimba.

C major -> G# major (+8 semi major)

We get interesting clusters here. 6 consecutive notes on the left, 2 sets of 3 notes chord on the right. All 7 notes fell down.

C major -> F# major (+6 semi major)

Only one 1 note on the board, this will be challenging! Probably the most difficult among the feasible major scales we can play on 34-key Kalimba.

C major -> A# minor (+10 semi minor)

This is how to get the most of upper tines on minor key, in other words it is a relative minor of that C# major scale we explored earlier because we have almost the same right notes and same wrong notes except the bass upper tines.

Bass upper tines are all out of keys. This looks really playable, and there are tons of 2 notes. (Was 7 on the C# major scale earlier.)

Because this is the same pattern as C# major earlier, you can again perform 1 semitone key shift up easily from A minor key. To get easy shift on minor key songs, transpose it to A minor then when the song gets emo to A# minor then play on upper tines. Bass notes are 2 and 5 only. Luckily we still have 2 instance of 1 note, with the low 1 almost fell off.

C major -> F minor (+5 semi minor)

This position gives you the root bass on upper center plus considerable amount of in-key tines on the 2nd layer. This is quite a spacious minor scale with three 1 notes available.

C major -> D# minor (+3 semi minor)

This minor position also have a single 1 3 5 combo in an entire board on the right side, and one more high pitched 1 on the left. If you want to play song in D minor, it is allowed to dip under the 1 note for a bit but no more room over the next 1.

The six practical positions for major and minor scales

In total I discovered 6 positions each for major and minor scales. For each type, 3 are centered around lower tines and 3 centered around upper tines. Upper tines version are on slight disadvantage since the center bass tines threw some wrenches in the equation

I will give my personal suitability rating as well and sort according to it.

Start with the lower tine-based shiftings in major :

• Main key ⭐️⭐️⭐️⭐️⭐⭐
• Mixolydian-like (+7 Major) ⭐️⭐️⭐️⭐️⭐
• Lydian-like (+5 Major) ⭐️⭐️⭐️⭐

And minors :

• Aeolian (Relative minor key, +9 Minor) ⭐️⭐️⭐️⭐️⭐️⭐
• Phrygian-like (+4 Minor) ⭐️⭐️⭐️⭐️⭐
• Dorian-like (+2 Minor) ️⭐️⭐️⭐️⭐

Then upper tines-based starts from 3 stars. The reason because middle upper tines are occupied by the basses and needs to be avoided most of the time unless stars really aligned. Plus when you play you need to be more careful not to accidentally hit the lower one.

• +1 Major ⭐️⭐️⭐️
• +8 Major ⭐️⭐
• +6 Major ⭐

Minors :

• +10 Minor ⭐️⭐️⭐️
• +5 Minor ⭐️⭐
• +3 Minor ⭐

This is the legend of stars :

• ⭐⭐⭐⭐⭐⭐ : Perfect, everything playable on lower tines.
• ⭐⭐⭐⭐⭐ : One note on upper tines required to complete.
• ⭐⭐⭐⭐ : Still centered on lower tines, but more notes on the upper.
• ⭐⭐⭐ : Centered around upper tines. Few notes required on the lower.
• ⭐⭐ : ️Slightly harder than 3 stars. More notes needed on the lower.
• ⭐ : ️Yet harder than 2 stars. Probably the hardest that is still practical.

Because each star has major and minor, C major Kalimba can play practically in 12 keys out of all common 24 keys (major & minor *12)! Though with varying difficulties, but thats something to practice on right? It's a skill ceiling!

Why don't we try making a table assuming the Kalimba is in other key, what keys could it practically play? Seeds Instrument 34-key Pisces is available in C and B. But just in case other companies follow suit with more keys.

Or if sorted by major/minor keys :

The table also reveals that the upper tine positions (3 stars difficulty and lower) are all sharpened of lower tines. (e.g. C G F -> C# G# F#, A E D -> A# F D#) This is because one semitone higher is an effective way to "blacken" everything in piano keys perspective, shifting the correct notes all up.

Remembering the "plus" from main key will be difficult, so for me personally I would like to rename them based on those stars I gave, inspired by Harmonica's "straight harp", "cross harp", double-cross harp" positions.

This is my personal "Sirawat's 34-key Kalimba positions". Naming format is by tines row which it is mainly on (upper or lower) and ordered by playability (1, 2, or 3) and finally is it a major or minor.

• ⭐⭐⭐⭐⭐⭐ : 1st lower major/minor position. (1LP Major/Minor)
• ⭐⭐⭐⭐⭐ : 2nd lower major/minor position. (2LP Major/Minor)
• ⭐⭐⭐⭐ : 3rd lower major/minor position. (3LP Major/Minor)
• ⭐⭐⭐ : 1st upper major/minor position. (1UP Major/Minor)
• ⭐⭐ : ️2nd upper major/minor position. (2UP Major/Minor)
• ⭐ : ️3rd upper major/minor position. (3UP Major/Minor)

Replacing the previous table, we get :

To make good use of these stars on my practice with my C key 34-key Kalimba, I of course should look to play C major and A minor key songs on mainly lower tines first. (Or transpose other songs to C major or A minor)

In addition, G major and E minor will be great and satisfying to pull of, and F major and D minor will be more challenging. Once I am good with that, it is time to explore 6 more upper tine-based positions once again.

Not sure if this result was intended by Seeds Pisces designer or not. But yeah, you created a monster! (That's a compliment)

That table's CSV was assembled from strings printed from Unity too. Thanks Unity!

Just in case you want to do something with it :

C,A,G,E,F,D,C#/Db,A#/Bb,G#/Ab,F,F#/Gb,D#/Eb
C#/Db,A#/Bb,G#/Ab,F,F#/Gb,D#/Eb,D,B,A,F#/Gb,G,E
D,B,A,F#/Gb,G,E,D#/Eb,C,A#/Bb,G,G#/Ab,F
D#/Eb,C,A#/Bb,G,G#/Ab,F,E,C#/Db,B,G#/Ab,A,F#/Gb
E,C#/Db,B,G#/Ab,A,F#/Gb,F,D,C,A,A#/Bb,G
F,D,C,A,A#/Bb,G,F#/Gb,D#/Eb,C#/Db,A#/Bb,B,G#/Ab
F#/Gb,D#/Eb,C#/Db,A#/Bb,B,G#/Ab,G,E,D,B,C,A
G,E,D,B,C,A,G#/Ab,F,D#/Eb,C,C#/Db,A#/Bb
G#/Ab,F,D#/Eb,C,C#/Db,A#/Bb,A,F#/Gb,E,C#/Db,D,B
A,F#/Gb,E,C#/Db,D,B,A#/Bb,G,F,D,D#/Eb,C
A#/Bb,G,F,D,D#/Eb,C,B,G#/Ab,F#/Gb,D#/Eb,E,C#/Db
B,G#/Ab,F#/Gb,D#/Eb,E,C#/Db,C,A,G,E,F,D

You can use these stars rating effectively like this : if you want to jam together with others perhaps while drinking with an acoustic guitar, a common problem is that they don't want to transpose the song just for you to be able to play on 1st position, but transpose down a bit from the original key mainly so the singer is more comfortable. (We are chilling so we don't want to get too high, and inexperienced singer that can't get high could join.) Guitar players can use a capo, but Kalimba player can't use a tuning hammer that fast. So you can remember this if you own a C Kalimba : C G F C# G# F# (major), or A E D A# F D# (minor) (all the playing positions in ascending star difficulty order) and ask for a compromise if we could get the key to be one of these.

Diagrams recap, lower tine positions :

Diagrams recap, upper tine positions :

New chord possibilities

With all the scales explored, also we have more ways to play chords that has out-of-key component.

For example, any time you play a major chord and its middle component lands on upper tine, you can move that down to instantly transform it to minor chord! And vice versa, any minor chord on lower tines can be turned into major by moving the middle component up. Quite good amount of songs unexpectedly play the major-minor inverted version of the chord to defy expectation of listener, we can now cover that with this 34-key Kalimba.

Other exotic chords may appear accidentally, like augmented or suspended chords that requires some notes closer to each other. I have not look closely at these yet but it will be interesting to play these sounds.

Conclusion

34-key arrangement on Seeds Instruments Pisces adds tons of entangled possibilities, just like how 6 open guitar strings gave birth to million of both practical and impractical chord shapes. If we figured out music theory behind a particular "system" produced by the instrument, chances are we will have a lot of fun stuff we could practice on! Overall, I am content with my 34-key Kalimba purchase and I will try to get better on it.

Ps. They made a new monster again called the Columbus. 24-key, but in ascending order, diatonic, allowing complete L-R hand multitasking like the piano. Some sick constant chords running while melody doing its own thing on the right side is now easier. Glissando always go from left to right. The most important appeal for me is that it goes high, a blessing for minor key music lover like me since when you play in A minor (relative minor of C major that most Kalimba came with), the upper range gets eaten up by the shift and make emotional part of the song fell off the edge.. This also looks fun! But I don't have any more spare cash to get another.. for now. 😂 Maybe, I will be back with an another analysis on the Columbus in the future!

Tibetan Breaking is a convention to encode line breaking opportunities inside the string data itself, using a Tibetan interpunct ⟨་⟩ character, called ཙེག་ (tsek). (Tibetan Script) From now on I will also call ⟨་⟩ the "Tsek".

All strings that does not have white space or similar to hint line breaking should have Tsek and parser should be prepared to remove them from display if they are not intended to print them out, or even better, converts them into real line breaking opportunities that enhances reading experience.

Note that line breaking opportunity does not mean it must break at that position like <br>, but it could. Presence of this character also means it should not break at any other places between characters, save for some punctuations that has language-specific rules.

Example

• ทุกวันนี้་จ่ายภาษี་ไปเท่าไหร่་ก็ไม่เห็นว่า་ประเทศชาติ་จะพัฒนา་เท่าที่จ่ายไปเลย
• 赤い་甲殻に་身を་包む、火竜とも་呼ばれる་飛竜་リオスの雄。

Why should we use this character

• It is inlined with the text. Line breaking opportunities being a single entity (as opposed to range surrounders like ** in Markdown), can be encoded as an accompanying array of integer offsets to the text, so the "clean" text is perfectly readable and editable. But it is now difficult to update the array after modifying the text. Having an actual character in the string is better. Also pairing different data to the string might be difficult to manage.
• Almost invisible when you don't want to see, but at the same time visible when you want to edit them. This is better than thin character like a pipe | where it may not take much space, it is obtrusive to read. And better than a completely invisible character like the Line Separator (Sometimes that even show up as a tofu box.) where it is difficult to notice that you are editing over them. (e.g. Pressing backspace and nothing happen, so that means you are deleting this invisible character.)
• Middle dot · character is almost as good, but Tsek has an advantage that it is usually not present in most monospace fonts. It then falls back to a font that is not monospace, making it ideal in code editor because it stays small.
• In online Localization collaboration platform, you don't need any special features to manage the line breaking opportunities. You may add a tag that Tsek is present to save processing cost for strings that does not have them at the destination.

Disadvantages

• You likely cannot type from keyboard, but having to copy paste it.
• If you are making a string of an actual Tibetan language, then the parser needs to know to print them literally rather than process them...

Relationship with other markup languages

Markdown's success came from it using a very humane markup format. We can both encode different highlighting that make different on the destination media, and also can read it aloud and feels like it has the same "highlighting" effect.

Tibetan Breaking is the same as Markdown that we are directly encoding more information inside the text. However for presentation, line breaking is naturally invisible so it make sense that this encoded information is the most invisible as possible when we read it in plain text editor. You can have Tibetan Breaking and Markdown together.

Tibetan Breaking is different that it use a single character Tsek, not surrounders like most of Markdown's syntax.

HTML-like "enriched text" format can sometimes encode a single entity (e.g. <br>) or surrounders (e.g. <strong>asdf</strong>) but neither are pleasant to read.

The need for explicit line breaking opportunity

Google's Budou documentation explained this very nicely.

English text has many clues, like spacing and hyphenation, that enable beautiful and legible line breaks. Some CJK languages lack these clues, and so are notoriously more difficult to process. Without a more careful approach, breaks can occur randomly and usually in the middle of a word. This is a long-standing issue with typography on the web and results in a degradation of readability.

In many places like website, text processor, game engine, etc. the "breakable at white space but not in between other characters" are hard coded. In east Asian characters, there are more characters hard coded to be breakable. They can also be limited to not be able to use at the start/end of line, so it works together with line breaking code.

One more hard-coded behaviour is that if CJK language is found, suddenly it is breakable at all characters. You absolutely don't want to allow this for English. But in CJK if you don't allow this, strings of character without any hints of space can easily exceed the line. They can't break intelligently semantically like human do either, so they must settle for this simple but not optimal break at all characters.

Other than this, many languages wants to break mid-strings but of course not anywhere. In Japanese, a string of kanjis can be broken into words with different meaning than intended, sometimes even 1 kanji is readable. In Thai, there are more chance to create a word that is readable cross-line but is not optimal as there is a long pause before your eye scan to the beginning of the next line.

Critical for responsive media

Unlike physical media like signs, strings can used in dynamic media. Line breaking tied with the width of that media. Nowadays websites could be viewed on mobile device. Even a smartphone games can be responsive to the device's screen and provide longer or shorter line depending on device, or even orientation you play on.

Here is an example from Budou's project page. モバイル (Mobile) and チーム (Team) should absolutely not be broken, but the algorithm is set to "breakable at every character" by default for Asian language. At the same time, we can't sneak in white spaces in Japanese language to hint the browser. Without manually marking line breaking opportunity you don't know at which width it will gives the reader sub-optimal experience.

Even the text above of this very blog broke in an unfortunate place at a certain screen size! Look at that unfortunate  ーム at new line that is not even readable...

Here is an example from Unity game engine, the default behavior which is the same as website. Each character is completely independent and breakable. Imagine the changing boundary as various phone size.

An ideal result :

Technical fixes is possible after having Tsek

This goes a bit beyond the purpose of this article but just for completeness. Supposed we had encoded Tsek in the text. How to decode them to use in the destination media?

On website, if you use Budou's way you can wrap each "chunk" in <span> with a class display: inline-block;, then all chunks inside an another empty <span>. (Though, Budou tries to use machine learning to automatically place breaking opportunity. Tsek has real human place them manually.)

An another way is to have the parent with white-space: nowrap to cancel out the built-in "break anywhere" of Asian language then place <wbr> inside the HTML. Be careful if you use white-space: no-wrap with English it will cancel out the already great white space breaking. So you need to be selective of languages. With this convention, you can check existence of Tsek character to activate white-space: nowrap without knowing what language it is.

Also, <wbr> simplify processing since you just replace Tsek with it. If you use <span> wrapping, it could be a problem when you have Tsek in the middle of interleaving surrounders that also needs to be processed.

In other system like game engine that supports "rich text" like Unity, you may wrap each chunk in something like <nobr>...</nobr> (non-breaking text) to counter the breakable anywhere rule of CJK language. Then in-between, ensure it is breakable with <zwsp> (zero-width space) to silently add hints to CJK language which has no hint before.

In summary, all these technical fixes while usable, are absolutely not ideal to be encoded directly in the text as they are horrible to read and edit, and interferes with good encoding like Markdown.

I don't know how to call this sort of internationalization scheme on a website so I coined it for my own use. Explaining this gets repetitive so I made this article to link to every time I wanted to talk about it.

What is this kind of article doing in a blog about game dev? This is my favorite kind of site to use for game's home page! It should maximize accessibility as it is common that you publish the game to multiple countries.

It has these characteristics :

No question asked, URL to choose the language

It is a site that use purely URL to choose which language to display. (e.g. example.com/th/about to display Thai version.) No cookies, no IP address detection can triumph over it.

Each language of each page exists for real as a separated HTML file. (But of course computer should do this for you, not manually.)

Direct edits OK

User can directly edit URL to go to a different language if they think that language code exists. This is ineffective on some sites that are "not dumb enough" and insist on displaying a certain language depending on your location, your browser, some settings deep in the cog wheel menu, or your cookie. And usually they will not tell you how the decision works. (I think this is frustrating rather than convenience.)

Unsupported languages

Unsupported language returns not found error (e.g. example.com/asdf/about) rather than a random redirection to default language. If all your language pages are really a separated HTML files, this should happen automatically.

Honest <a> links

All <a> links inside a specific language should contain the destination of that language for real. e.g. example.com/th/about has a link to go to example.com/th/contact but not a "neutral"  example.com/contact that you may need to rely on other tricks to finally come back to the right langauge.

When user hovers the mouse, they should see that clearly appearing on the browser's corner.

We make the crawler life as easiest as possible.

Neutral page

If user type "neutral URL" (no language slug) of any page, that page exists for real as an HTML file as well. The language is of a fixed default language (e.g en). Therefore it is a duplicated file of one of the language you supported. Again, machine should perform this duplication on building the website, not you.

Those neutral URL may use rewrite technique (serve same content, URL unchanged) according to something like navigator's language or visitor's IP address to instead show a content from language specific page, while not touching the URL. If rewriting fails (no specific page supported), then show the neutral HTML as a fallback.

Note that with rewrites instead of redirection, user can copy the URL and share it without making their own country appears in the URL if they just visited the page and hadn't navigate anywhere else yet.

But as we use rewrites, all the links in that page will go to language specific page according to "honest <a> links" rule. Navigating once from the rewritten page will turn back into "honest" version with language in the URL.

The neutral page allows putting your homepage URL without country code on a printed media and use it (e.g. a poster) in multiple geolocations.

Also, search engine crawlers may appears to come from multiple countries. If you do this right, the neutral URL will present different content to the crawler. This is great, as Japanese user coming from the search engine will see Japanese content, but the URL is example.com and not example.com/jp. (Though any navigation performed next will adds jp)

• Some static hosting site has some config exposed to help you do this. For example Firebase Hosting has i18n rewrites.

Rich metadata, crawlers are welcomed

Rely on search engine so user of a specific country get to the page on the first time with the right language.

It knows all its alter-ego

Each page has <link rel="alternate" hreflang="x-default" href="HOST/NEUTRAL_PATH" /> and all other <link rel="alternate" hreflang="LANGUAGE" href="HOST/LANGUAGE/NEUTRAL_PATH" /> so all pages knows each other.

Each page has <meta property="og:url" content="REAL_HOST/LANGUAGE/NEUTRAL_PATH" /> of only its own, with the right language code. This make it works with Facebook and Twitter.

Read more about it here. Use the HTML tags way.

Localized <head> content

• Localized <meta name="keywords" content="keyword1, keyword2, ..."/>.
• Localized <title> and <meta property="og:title" content="..."/> and <meta name="twitter:title" content="..."/> (max 70 characters for Twitter).
• Localized <meta name="description" content="..."/> (for Google, search engines), <meta property="og:description" content="..."> (Open Graph, Facebook) and <meta name="twitter:description" content="..."/> (max 200 characters for Twitter).
• Localized social image, for example if they contain a lot of text or your product logo if you localized it.
• The Open Graph image <meta property="og:image" content="..."/>
• The Twitter image <meta name="twitter:image" content="..."/>
• Alt image description for the visually impaired : <meta property="og:image:alt" content="..." /> and <meta name="twitter:image:alt" content="..." />.
• If your page is for an app, localized <meta name="twitter:app:name:iphone" content={appName} />, <meta name="twitter:app:name:ipad" content={appName} />, and <meta name="twitter:app:name:googleplay" content={appName} /> for use with app-type card on Twitter.

What about <html lang="">?

Actually all tags are able to accept lang attribute. This would be ideal if all of your <div> soup has lang but I think it would be a major pain. (MDN)

So how about just put the right lang=" " inside <html>? It maybe a good idea but note that Google recommends nothing about it in this page. Therefore I think this is not an issue if you can't do it from your framework.

Honest language switcher

If there is no dedicated "switch language page" and each page has a dropdown, modal or a list to select all other versions, all those are plain <a> link that goes to the same page but with different language. (e.g. Clicking on "JAPAN" while on example.com/th/about links you to example.com/jp/about, not resetting to example.com/jp.)

That is an inverse of honest <a> links, where it preserves the language but go to a different page.

That means if you go to a different page, the component for switching language which may just looked the same as in previous page, actually has all its link adjusted.

Again! This might sounds painful to do it manually but you should use the power of modern web programming to do it for you in your front end framework of your choice.

Only just enough strings sent to client if possible

You might be using i18n packages that could accept an object kinda this shape :

{
  "en": {
    "term1": "value1",
    "term2": "value2"
  },
  "th": {
    "term1": "value1",
    "term2": "value2"
  },
  "jp": {
    "term1": "value1",
    "term2": "value2"
  }
}

Then using "current language" switch, any key request (e.g. format("term1")) will get the right string.

If your site is not hydrated and any  <a> link traversal is really going to a new page, the HTML can contain the most minimal strings needed for that one page in that one language.

If you need interactivity, for example the site hydrates and changing page now swaps DOM instead, then try to lazily add more strings. Because now if you consider switching language a hydrated action also, you will need strings of all pages of all languages ready. Popular solution is to preload more only when user clicks the link or even when hovering over the link.

Strings are usually small, so I think this rule is not that critical. I doubt even having all strings, of all pages, of all languages at the first load is even that costly for most site.

Example

Anyways, I have been trying to make a site of my own game to follow this pattern as much as possible : https://duelotters.com/. You can take a look for example, or even view the HTML source if each language is really dumb or not.

Note that the source looks alien since it is built with Svelte + Sapper, and the code in there is designed to perform direct DOM edit as is the characteristic of Svelte. (As opposed to DOM-diffing with React or Vue.) You need to figure out on your tooling stack of choice how to achieve the "dumb" status. Next.JS, for example, already has i18n routing which should help you work out.

And that's all! Maybe it doesn't sounds "dumb" after you see all the repetitive but-slightly-different HTML files needed for each page, but it is in a sense that it works rather in a straightforward way from visitor point of view. You are the site's developer should take the pain... luckily modern site building tools are great.

Using EventSystem along with GraphicRaycaster, PhysicsRaycaster, or Physics2DRaycaster, and something didn't hit the way you expect it to? Let's dive into the code to debug this.

ps. it's been a long time since the last one! I was away from game development because I got a real, totally unrelated to my passion, boring front end job that actually pays.. lol

Example problem

A game about clicking cookie coming into the screen. They are all 2D so I used Physics2DRaycaster. However, when touching any other area that is not the cookie we need to play some effects at that position as well.

Therefore on each cookie CircleCollider2D has been attached along with IPointerDownHandler or EventHandler setup properly. And there is one more FullScreenTouch to handle the miss-touch. This one is a BoxCollider2D.

• I assume you know EventTrigger only ever trigger one candidate at a time. How that candidate be selected?
• There is only one EventTrigger in the scene. Otherwise you get tons of warning spam. It is a hub to get all kind of raycasters in the scene.

What is an EventSystem ?

If you are an old timer Unity developer, you may used to "dumbly" place Input. check in some of your Update and if this and that, things happen. Then left click only works in editor, so you add Input.touches check, etc.

Actually EventSystem is not far from that at all. It has Update rapid check that eventually leads to Input like I described. Except that they made it more systematic. I recommend follow into EventSystem code and see its Update for yourself.

• Input initiator is already coded. If left clicking works in editor, then at runtime a touch also initiate the same code.
• What to do is determined by raycasting, which the EventSystem could collect all casters and gather candidates, and pick the best one. The candidate is further filtered by event type, such as pointer up.
• You perform additional checks with a given BaseEventData or PointerEventData given on your candidates. The input's details are collected in that data. Note that if you aren't satisfied with the input coming it, it is not possible to "let it go" and bubble up to the next candidate. This object had already been picked by the EventSystem. You have to write more custom logic to do that.

Problem

The plan is to have the cookie take priority.

• However, turns out the cookie didn't get trigger at all, only the FullScreenTouch one.
• More observation, as soon as I disable the full screen box collider the cookie get triggered. This means the cookie collider logic is correct and could trigger, but the bigger box 2d ones always get the priority.
• No, moving the cookies to Z = -0.01 doesn't make them win the selection.

Why?

Assembling the candidates

It all starts on RaycastAll method in EventSystem when you do something. You can manually invoke it! But if you use your mouse to click, then the invoker is probably StandardInputModule.

        /// <summary>
        /// Raycast into the scene using all configured BaseRaycasters.
        /// </summary>
        /// <param name="eventData">Current pointer data.</param>
        /// <param name="raycastResults">List of 'hits' to populate.</param>
        public void RaycastAll(PointerEventData eventData, List<RaycastResult> raycastResults)
        {
            raycastResults.Clear();
            var modules = RaycasterManager.GetRaycasters();
            for (int i = 0; i < modules.Count; ++i)
            {
                var module = modules[i];
                if (module == null || !module.IsActive())
                    continue;

                module.Raycast(eventData, raycastResults);
            }

            raycastResults.Sort(s_RaycastComparer);
        }

For each module, amount of candidate it could gather depends. In my case, the setting isn't wrong. I have allowed two. So it would get at least the background and one of the cookie provided that cookie can't ever overlap. 2 here is correct. And the raycaster gathered them in.

But the key is that raycastResults.Sort. Only the first one of sorted result will win and get invoked appropriate event handler.

You probably noticed your UI things always win and it didn't let the event go through anything under it. Well, things under it actually are gathered but after the sort the UI ones always win.

Raycast comparer

This is the destination for your raycast debugging needs. When something doesn't trigger as you expected.

private static int RaycastComparer(RaycastResult lhs, RaycastResult rhs)
{
    if (lhs.module != rhs.module)
    {
        var lhsEventCamera = lhs.module.eventCamera;
        var rhsEventCamera = rhs.module.eventCamera;
        if (lhsEventCamera != null && rhsEventCamera != null && lhsEventCamera.depth != rhsEventCamera.depth)
        {
            // need to reverse the standard compareTo
            if (lhsEventCamera.depth < rhsEventCamera.depth)
                return 1;
            if (lhsEventCamera.depth == rhsEventCamera.depth)
                return 0;

            return -1;
        }

        if (lhs.module.sortOrderPriority != rhs.module.sortOrderPriority)
            return rhs.module.sortOrderPriority.CompareTo(lhs.module.sortOrderPriority);

        if (lhs.module.renderOrderPriority != rhs.module.renderOrderPriority)
            return rhs.module.renderOrderPriority.CompareTo(lhs.module.renderOrderPriority);
    }

    if (lhs.sortingLayer != rhs.sortingLayer)
    {
        // Uses the layer value to properly compare the relative order of the layers.
        var rid = SortingLayer.GetLayerValueFromID(rhs.sortingLayer);
        var lid = SortingLayer.GetLayerValueFromID(lhs.sortingLayer);
        return rid.CompareTo(lid);
    }

    if (lhs.sortingOrder != rhs.sortingOrder)
        return rhs.sortingOrder.CompareTo(lhs.sortingOrder);

    // comparing depth only makes sense if the two raycast results have the same root canvas (case 912396)
    if (lhs.depth != rhs.depth && lhs.module.rootRaycaster == rhs.module.rootRaycaster)
        return rhs.depth.CompareTo(lhs.depth);

    if (lhs.distance != rhs.distance)
        return lhs.distance.CompareTo(rhs.distance);

    return lhs.index.CompareTo(rhs.index);
}

It is a series of return. That means this is a steps with earlier one having priority over. If we go through each one, surely we could debug anything!

Event camera

Raycast begins from a camera. Which camera has closer to you depth, then that wins the sort.

Raycaster kind priority

Then sortOrderPriority and renderOrderPriority which depends on raycaster. This is why GraphicRaycaster for UI always win the sort. But my problem is the battle among Physics2DRaycaster. Let's move to the next one.

Sorting layer and sorting order

All GameObject has a layer.

That could be used on the raycaster so candidates are further reduced. You can combine multiple layers into a mask.

However "sorting layer" here is not that. It is an event system specific value which is :

        /// <summary>
        /// The SortingLayer of the hit object.
        /// </summary>
        /// <remarks>
        /// For UI.Graphic elements this will be the values from that graphic's Canvas
        /// For 3D objects this will always be 0.
        /// For 2D objects if a SpriteRenderer is attached to the same object as the hit collider that SpriteRenderer sortingLayerID will be used.
        /// </remarks>

        /// <summary>
        /// The SortingOrder for the hit object.
        /// </summary>
        /// <remarks>
        /// For Graphic elements this will be the values from that graphics Canvas
        /// For 3D objects this will always be 0.
        /// For 2D objects if a SpriteRenderer is attached to the same object as the hit collider that SpriteRenderer sortingOrder will be used.
        /// </remarks>

Now I could see why I am having a problem right now. The wording may not 100% suggest this but I have look at other area in the source code : to qualify for "3D object" you need SpriteRenderer attached. Otherwise your layer/order is 0.

It happen that I thought my invisible full screen box collider didn't need any graphic so I didn't add SpriteRenderer.

My cookies surely are otherwise you can't see them. Let's look at the layer first. (Because the order tied at 0) They are Important.

My Important happened to be behind Unity's Default which I think defines a 0 in integer value. So that's why the cookie didn't get clicked!

Moving the cookies over Default is no good either since that will affect rendering.

Solution : Add SpriteRenderer to my box 2D collider though I didn't want any graphics, then set layer to maybe NotImportant so it loses in sorting. At least I know how to debug this now.

My problem is solved but there are more to go.

Depth

This is different from camera depth earlier. It seems to be for equal distance graphics to win over each other. Which means the UGUI system. They are often on the same plane. Look at this comment :

        /// <summary>
        /// Absolute depth of the graphic, used by rendering and events -- lowest to highest.
        /// </summary>
        /// <example>
        /// The depth is relative to the first root canvas.
        ///
        /// Canvas
        ///  Graphic - 1
        ///  Graphic - 2
        ///  Nested Canvas
        ///     Graphic - 3
        ///     Graphic - 4
        ///  Graphic - 5
        ///
        /// This value is used to determine draw and event ordering.
        /// </example>

This is why dragging around UGUI object in the Hierarchy tree has effect in both draw order sorting and also winning over in raycasting. This won't applied to non-UGUI objects.

Distance

Finally, is it surprising that distance comes the last? This is why I moving the cookies a bit closer to the camera doesn't work out because there are many other criteria that came before.

async already works in Unity without any kind of plugins or coroutine wrapping the Task and pseudo-async it by checking completion every frame. But it is kind of magical. Let's try to dig into it a bit more.

(Note : I am still confused by the whole C# async / await inner workings, I should add more once I understand everything throughly.)

Example

I would like a Button that when clicked, would play a classic Animation on the box. But there is a catch : the button should turn into disabled state (greyed out via .interactable) until the box finished spinning.

But I would like a cleaner code, I want to use await until the box finished spinning and immediately put a line that interactable is restored right after. Instead of something like spawning coroutine host game object to check the state every frame and do work afterwards. Having code in the same place linearly is a big plus to readability. It's very fun to write such code.

With a code this simple, it already could achieve what I said. ( async method still show up in Unity's delegate picker just fine, don't worry.)

using System.Threading.Tasks;
using UnityEngine;
using UnityEngine.UI;

public class SpinBox : MonoBehaviour
{
    public Button button;
    public Animation ani;

    public async void SpinAndDisableButton()
    {
        ani.Play();
        button.interactable = false;
        while (ani.isPlaying == true)
        {
            await Task.Yield();
        }
        button.interactable = true;
    }
}

Questions that should come to your mind :

• "Who" is "running" the while and the rest of method? Why is it getting checked in the next frame magically when the call to SpinAndDisableButton is only once, and there is no Update or coroutine whatsoever to repeatedly run it.
• What is the timing of each run?
• What is Task.Yield() ? It seems to be the key to everything here. I assume you used to yield return null in coroutines. That is a clever to say try again the next frame but you are talking via C# enumerator. The "yield" wording is similar, and even the behaviour is similar.

Synchronization context

Check out this article : http://hamidmosalla.com/2018/06/24/what-is-synchronizationcontext/ how the rest of the program could be captured and continued in a way we like (e.g. on which thread? on the caller or on the thread that run the task?)

Then we will see Unity also have such a thing too but it is not visible to us at first glance.

Compared with regular C# program

It's not quite like normal C# program. Looking at this official await documentation. await means return to the caller as a Task. The caller could go on, until it need the execution result and can't afford to do something else in the mean time anymore (it doesn't matter the task is truly multithreaded or not) then caller can await. This chain can continue until you finally arrive at Main. Where if also async, there is an another await generated by the compiler that ask for result immediately.

Now look at our SpinAndDisableButton again. await returns to who? We have no Main in Unity as it is tucked deep in the engine code. The question is now the same as who is running Update, LateUpdate and so forth. It is the PlayerLoop API that the engine code run as a part of game loop to ensure orderly render submission and things goes in frame unit. But we used to not care since until now those entry point returns void.

Now the await is returning the execution point to that someone in hope that it could continue from the same point later, at a certain moment, automatically. Then continue with the game loop while await that. Otherwise we wouldn't seeing a spinning box at all if we really await until the box finishing the animation, because animation can't finish unless the frame goes on. What exactly would happen the next frame?

This is a pseudo code we want to achieve in a frame other than the frame that we pressed the button and disabled the button :

for (gameLoop)
{
    if(box animation finished)
    {
    	Button is enabled.
    }
    Animation advances.
    Send box's transformation matrix for rendering.
    We see a new box's rendering.
}

Debugging

Putting more logs into the code and we will try debug stepping.

using System.Threading.Tasks;
using UnityEngine;
using UnityEngine.UI;

public class SpinBox : MonoBehaviour
{
    public Button button;
    public Animation ani;

    public async void SpinAndDisableButton()
    {
        Debug.Log($"Started async {Time.frameCount}");
        ani.Play();
        button.interactable = false;
        while (ani.isPlaying == true)
        {
            await Task.Yield();
        }
        button.interactable = true;
        Debug.Log($"Finished async {Time.frameCount}");
    }

    public void Update()
    {
        Debug.Log($"Update {Time.frameCount}");
    }
    
    public void LateUpdate()
    {
        Debug.Log($"Late Update {Time.frameCount}");
    }
}

The update order turns out like this :

• The frame where we start the animation, it came before Update and LateUpdate because the mouse clicking is thanks to EventSystem and GraphicRaycaster of Unity UGUI, which happens to have Update execution order before any of your scripts.
• The while awaiting seems to occur magically every frame from that point, the timing is after Update but before LateUpdate. It like we have spawned a coroutine but we haven't!
• One interesting point is that at the first frame where we just issue the animation playing, there is 2 Awaiting in the same frame since UGUI event system came even before. Suggesting that await "subscription" is immediately effective without need to summarize or anything in the next frame.
• In the old days we would have to put a check in Update or something. This await subscription elimiates the need of that.

What's left is to demystify the "awaiter", which I didn't get it completely but at least I see it works because it was intentionally coded in.

The first frame where I clicked the button there is nothing strange. Update (the same magical MonoBehaviour Update) of EventSystem uses Input API and see that I clicked, it pseudo-raycast into my canvas button and see that it could do something. Then it invoke into this public async void and arrive at this line. (You can manually use this ExecuteEvents too! It is a helper static class.)

The next frame around where magic happen, the call stack could reveal exactly who is working the check for us every other frames. This is the point where I didn't exactly understand what's happening here. (though it works)

When checked the UnitySynchronizationContext, many seems to be called from engine code so I can't really do anything but guess.

But there seems to be something called WorkRequest that represent each of your unfinished business awaited. I could guess that the await returning is properly registered, in a "game" way, that is friendly with frame paradigm and ensure all safe code locked in main thread, so you can truly do anything after any await because it is at the right moment in the frame.

Task.Yield()

This method got really confusing summary :

https://docs.microsoft.com/en-us/dotnet/api/system.threading.tasks.task.yield?view=netframework-4.8

Returns
YieldAwaitable

A context that, when awaited, will asynchronously transition back into the current context at the time of the await. If the current SynchronizationContext is non-null, it is treated as the current context. Otherwise, the task scheduler that is associated with the currently executing task is treated as the current context.

Remarks

You can use await Task.Yield(); in an asynchronous method to force the method to complete asynchronously. If there is a current synchronization context (SynchronizationContext object), this will post the remainder of the method's execution back to that context. However, the context will decide how to prioritize this work relative to other work that may be pending. The synchronization context that is present on a UI thread in most UI environments will often prioritize work posted to the context higher than input and rendering work. For this reason, do not rely on await Task.Yield(); to keep a UI responsive. For more information, see the entry Useful Abstractions Enabled with ContinueWith in the Parallel Programming with .NET blog.

I am not English native, and I think neither C# yield return or Task.Yield() convey the function it performs. But let's go with the method definition.

An intended use case in the remark seems to say that the method is actually not async but you would like to turn it into async so you need an await somewhere in it, therefore Task.Yield() is the perfect scapegoat, or something. Instead of finishing the method right away (remember that async won't magically turn the method to async, it depends on the content of the method) now you force it to be async.

But in our case the context receiver is not an ordinary context but UnitySynchronizationContext. Now the Task.Yield() has a more useful function that effectively continue things the next frame. If it was an ordinary SynchronizationContext, I guess it could produce infinite loop in our example program since it would continue to the while again right away.

It returns a YieldAwaiter that the caller could use to continue. As evidence from our log, "Awaited" was logged every frame onwards becuase the context (code next to the await) was saved into this awaiter. UnitySynchronizationContext do something magical and wait a frame and use this awaiter to continue, then it hit while and once again return a new YieldAwaiter. This probably continue adding a new WorkRequest for the code earlier every frame as a pending task until the while is false.

UniTask

There is a popular UniTask (https://github.com/Cysharp/UniTask) package that eliminates SynchronizationContext altogether and make a new kind of lighter task UniTask that binds to PlayerLoop API directly. You could then choose the timing when should the awaiting check would happen in the next frame. (Initialization? Late update?) But essentially, you know await works without any kind of plugin. It will be useful with Addressables where AsyncOperationHandle could be .Task that you can use with await.

Read

Here are more links that will reinforce your knowledge of C# await pattern :

• await anything; | .NET Parallel Programming (microsoft.com)
• Extending the async methods in C# | Developer Support (microsoft.com)
• JacksonDunstan.com | How Async and Await Work
• How to use Async-Await instead of coroutines in Unity3d 2017 | Steve Vermeulen

The last one highlights a particularly important weakness of Unity's iterator block pattern where you cannot return value or handle exception good enough, and the gotcha you may get when transitioning from non async method and just plainly call async method. If you are not careful, your exception will be swallowed into the Task and that is scary. There are some consideration of choosing between async void versus async Task.

• Dixin's Blog - Understanding C# async / await (1) Compilation (asp.net)

This one is so good! It demystifies that async and await disappeared into a regular method returning Task, while replacing the body with a state machine. The state machine's MoveNext will advance an integer each time. Each await in your body are sliced into sections belonging to each integer. And finally returning the result at the final state. You will see more clearly too how GetAwaiter() works and how your custom one will fare in the state machine.

Watch

This is a good talk that show await already works, but there are pros of coroutines that justify its usage. You could stare at this slide for a while to get a grip if you are still confused.

I switched from Atom to VSCode years ago simply because I like blocky and flat UI, but soon I discovered that VSCode has just the right amount of features yet well tucked away from view. But what leads me to evaluate Rider now?

Visual Studio Code is almost perfect, very very few annoyances. But in this competitive scene of text editor, it is tempting to pay just to eliminate those annoyances from the tool I touch every day. (Of course, after knowing several years passed with no resolution about them.)

Rider is not even famous for these annoyances fix I would like to pay for. It is famous for its "intelligence" as an IDE or deep Unity integration, that I am not really care at the moment. I just want a beefed up text editor like VSCode but without little flaws. Let's see if Rider can fix them. And how to modify Rider so it looks more like VSCode, so I could get both bug fixes and simple looks.

• What better or worse things in Rider compared to VSCode.
• How to make Rider more like VSCode for those who liked VSCode, but just want that one bug fixed or that feature added now without waiting for submitted issue to be resolved in VSCode.
• I will go as far as very little polishes, since fundamentally all modern code editor could do the same job. It's these details that make a difference.
• Rider version evaluated is 2019.3.

Fallback perpetual license

The first thing you may think as soon as you notice that the business model is a subscription based in their website : "I don't want to subscribe to a mere text editor!!" Well text editor is our tool of the trade and is hard to perfect so you may need to reconsider its worth.

Anyways, I would be fine with one-off payment. I was put off by the subscription model because of insecurity of having to pay indefinitely.

Until I see that they offer this. Basically, when you stop your 1 year subscription you simply stop receiving updates and can continue using your version back when you first started. Also you can extend for a few months if you would like to stretch the coverage to get new features that match your use case then you could stop there.

Unlike Adobe for example which they will prevent you from using the tools completely. This is very nice and made me change my mind about purchasing Rider. Yes, it feels more like purchasing this way and I may even continue the subscription because they are generous. More information here.

VSCodeVim vs IdeaVim

I rely on Vim key bindings daily, and VSCodeVim has lingering problems that was unfixed for multiple years :

• gd to jump to definition usually works fine, but the reverse Control + O often return back to wrong place or throw dialog box error.

• The plugin doesn't count code refactor as an undo step, when you do something next to a refactor and undo, you undo that step plus the whole refactor.
• Code snippets with variable transformation doesn't work when this plugin is on.
• Macro recording qq playback "too literally" and sometimes missing some movement commands causing my plan to fail. Also it is quite slow, if the command is long then I can see it doing things as I wait for it to complete.

I evaluate IdeaVim for a bit, it seems to not have any of mentioned problem. But instead :

• == or =i( to format code in IdeaVim doesn't work, while it works in VSCodeVim.
• gc for commenting in visual mode is not implemented, but it is in VSCodeVim. I have to resort to Cmd+/ normal shortcut.

There is always something missing in any Vim emulation!

I understand that I should not feel entitled to have a bug-free VSCodeVim where it is an open source project with tons of open issues on GitHub. If I am not willing to contribute, then I have no right to demand things from them. However it is also true that I don't have time to study how to contribute, and IdeaVim is a company maintained solution that I could spend money on instead of time. I guess this is where money could motivate you and result in a more polished product.

IdeaVim is fast!

Maybe this alone worth the price. As in, in VSCode when you turn off VSCodeVim even simple line movement command is slower than you press down arrow with plugin off. It is apparent in a command that jumps over distance like Shift + ].

It feels like VSCodeVim went through "something" before it could move. Maybe you won't feel it, but I am a music gamer and a game developer. I can tell responsiveness difference. Using real Vim like the one in Terminal or MacVim, the feel of responsiveness is very similar to Rider, but not to VSCodeVim.

(I am not saying Rider is faster than VSCode, that is impossible since Rider is more of an IDE. But if only the IdeaVim part, then it is faster. And it worth noting here that this text editing is the core part of programming experience, not start up time.)

Omnisharp vs ReSharper

Omnisharp works fine most of the time, including project-wide variable rename that's important to my workflow so I can name my variable mindlessly when drafting up quick code.

In a very complicated case however it fails. For example, this variable in a lambda-in-a-method doesn't auto complete, where it does in a simpler lambda. This pattern is important in Unity's ECS library.

ReSharper is well, sharper...

Also I should mention ReSharper start up faster than Omnisharp. VSCode has reputation of being very fast, but that's not counting the time until your C# project truly come alive. In Rider, starting up the program itself is quite slow. But it is fully usable soon after. In the end I think total time is about the same.

Code completion dialog size

From the earlier screenshot, one thing VSCode get a win from me is the super compact code completion dialog. Rider one is way too wide and line height is too big. And there is no way to change this. You can drag the right edge to narrow it, but when it appears again it expands to the longest entry that maybe deep below and you are not likely to access it. In Unity ECS, the verbosity cause this dialog to get unwieldly almost always.

And I really hate it when it go upwards, erasing all my context that I am thinking with. This is because the height is too high. If I could set it to about 4-5 entries then it could have fit below just fine.

Here's from VSCode. Small and cute. There is no need to show the whole thing. ... is fine 95% of the time. The documentation balloon is equally compact.

Meahwhile look at this Rider documentation balloon. It's huge! And it can also appear if you linger around the code completion box for 1 second, adding up to the clutter. I ended up turn it off because it was too obtrusive and always decided to go upwards.

And it is hell with ForEach lambda that contains million of permutations of valid lambdas, basically you take a lag punishment for waiting more than 1 second inside a lambda, that I have to turn it off. Then when I am using a normal method I have to go to definition to see the signature... damn.

Code completion performance

Rider is slow on completion! The VSCode one feels like "just" a string replace. However in Rider you can type ahead of the result and the keystoke can catch up later. It must be because of reformatting stuff and other intelligence. I think I can live with this, but VSCode is more snappy when choosing a code completion. (Also with template/snippet)

This offset with faster Vim performance in Rider however. Moving around the cursor is faster in Rider.

The look can be matched, somewhat

I like VSCode's minimal and blocky look. Some don't like full blown IDE like Rider not because it has heavy startup time, but it looks heavy. You know that feeling when you open Android Studio. You feel tired even before you start working.

Startup time asides (I don't really care), I could strip off bloated look from Rider until it looks empty just like VSCode. The most important point is one level of top bar. Then one level of bottom bar. And then eliminate the surrounding side bar of features (with rotated text like "Project", "Ve.. that's so distracting) that make you feels like you are coding in a box. You go to View > Appearance to do this. Anti aliasing off on fonts make me alert, it is possible in Rider too in the preferences.

Target

Before

After

With side bar off. Just top and bottom border now.

Editor theme

Rainglow theme is also available on Rider. I like changing themes depending on mood rather than trying to "master" a theme, so that's perfect. But there is one thing I like in VSCode, the theme extends to the side bar and not just the editor area. For example this more brown theme, the Rider dark that was fine in the screenshot earlier now looks weird because there are now 2 kind of different temperature of dark. But I hide the sidebar when not used anyways.

Taming rules

Rider came with rules built-in and my code are all moaning. Luckily I can tame them by clicking the light bulb and select what I want instead of digging preferences.

I do think they are too much sometimes, such as the var naming rules. They offer a rule about do/don't use var for simple type, or do/don't use var for when it is "evident". But in real code it is more complicated than that. When I use ToComponentDataArray<T>, it is to my eye "evident" that the type is gonna be NativeArray<T> but of course the rule can't "see". The out var pattern is often conflicting with some rules. And finally sometimes I arbitrarily use or not using var based on how busy the surrounding. (The combined JobHandle need it for emphasis, but the handle returned from out var I don't want to type out JobHandle, etc.) I ended up turning off many of the rules.

In VSCode's first few days I do have to turn something off such as code lens (I hate when my characters move around on their own) or folding, but there are more to turn off in Rider. I spent about 2-3 hours to config Rider fully.

Some rules are annoying though, like float == where I used 0 as special value to trigger some logic. (I don't want to make a new bool)

Code Snippet vs Live Templates

Rider's Live Template wins.. because it works with IdeaVim while VSCode Code Snippet cannot perform parameter transform while in VSCodeVim. Yeah it's all about Vim for me, can't be helped...

Here is an example of snippet config file from VSCode. Each $ represent where your cursor will go on each tab. You can perform some transformation with regex on them. See more : https://code.visualstudio.com/docs/editor/userdefinedsnippets

In Rider, I like that I can name my variable whatever I want like $type$ here. I haven't read yet how to perform variable transform. (So the type name inside <> could also become variable name but in camel case, for example.)

Follow deep into the package

VSCode do not understand Unity, and when you try to follow something into the package, it ask the C# project file and found that it is a dll, and so it dig into the dll (generated from asmdef) instead of an actual package source code that is also available somewhere else.

Rider is winning here, because it knows about Unity UPM packages. If you follow into  EntityCommandBuffer.RemoveComponent for example :

You can get into the package with Rider. This is very important in modern Unity as source code are all available. You no longer have to wonder what happen inside when you can just gd into it then out quickly with  Ctrl+O. (Vim commands) It is possible to turn off all the documentation popup with this. I think it is better as popups are distracting, let the code completion box be the only one.

(Though the VSCode dll version one is useful to quickly see the neighboring overloads such as which one has EntityQuery overload, though you can use the outliner in Rider too.)

Peeking

Red hot in Rider 2019.3, you can do this to peek the definition :

VSCode could do it from long ago. Personally I like the VSCode one better because it works well with its "boundless design" by filling horizontally. Also..

Matching find usages behaviour

That peeking UX is very well used in find usages. Now the part at right has a browsable list.

I don't like this massive tree of usage result that Rider presents me. It's clunky, and I can't see the code immediately like in VSCode while retaining old context.

VSCode later even improve by adding a more complete version of find usages, which is still better than Rider's presentation. Just a file and lines where that appears. No need to present me a tree.

Luckily there is a way to match Rider to this look. First, click the cog and select Left Top.

And to eliminate useless folder entries on the tree and make it simpler like VSCode, it's in this Group By menu. Uncheck things from top until it is useful for you.

If you like the peek style in VSCode, move to Bottom Left again and select the bottom left corner button "Preview Usages".

The VSCode one again for comparison. It is just that the code is on the opposite side.

Matching file browser behaviour

Click this not so descriptive "Always Select Opened File" button with down arrow so it works like VSCode. When you use Search Anything, the browser then focus on that file. I prefer this more than breadcrumb at top (which I turned off) because I could see the surrounding contexes and I could eliminate the height of top bar to just the tabs like in VSCode.

That button on the left with opposite side of arrow, make it so a single click open the file like in VSCode. (The icon looks equally no so descriptive..)

Rename refactoring

In VSCode it is deceptively simple, but feature complete. On pressing F2, there is a little box where if you type something else it updates the entire project such that there is no error. (If the name didn't conflict.) And it is fast!

Rider is not only slower as it is more careful to update an entire web of project, and also comments, but I don't know why sometimes it gives a dialog box. (And this version is quite slow.)

Sometimes the same shortcut gets me a little box instead (I want this all the time...) I guess it is when it is a local variable?

Also I am not a fan of Rider's small box rename that constantly updates the same thing nearby as you type. It seems to be more impressive that way, but I like the way VSCode did that they only commit ripple changes after you press enter.

Unity aware project browser

Something I found nice, Rider's looks like Unity's Project panel. The blue box indicates a folder with asmdef inside it. It works with nested asmdef too.

At first I was not a fan of colored icons, but I do look the cartoonish bordered look on them. The shade of yellow they choose is nice, fortunately.

Annoying save behaviour

Rider seems to love to save your file automatically, or do something too transparent that you ended up feeling insecure if it was saved or not. This is hell with Unity where iteration time is a very well known problem.

For instance when you tab back to Unity all files are automatically saved. You cannot left the file in dirty state and go take a look at Unity and come back. You will have to face the 5-10 seconds freeze every damn time. Luckily you can turn this behaviour off :

More weird things you cannot turn off :

• When closing dirty file it will not ask you anything, it will just close it after saving automatically for you. Seems nice, but sometimes I perform stupid edit and wanted to throw those away but now I have to repeatedly press undo. This maybe better if you are more discipline with your version control so you can only revert back to a commit, but it made me feel less in control by removing the save dialog.
• You cannot save a file individually. There is only "save all". This is also weird but in VSCode I always press save all anyways. For me this is welcomed.

Auto-recompile after saving

After fixing the previous annoying point, it turns into a new good feature. Now you can press Save All while in Rider, then you will see Unity reacts and recompile as if you performed the Alt+Tab x2 trick you used to do in VSCode to force Unity to recompile.

I am getting used to this. Usually it goes like : I am done with a section of code and press save manually. I spend time glaring at it for a few seconds, then think "Ok double checked. Nothing wrong!". But by the time I finished checking, Unity has done compiling my new code since it triggers as soon as I press save. It now feels like tabbing back to Unity is instantaneous.

If Unity managed to fix their iteration time to be under 500ms in the future, this will be even more beneficial.

You can limit tab count

As you follow definition and open many files you ended up with a lot of tabs. I like this option that automatically close tabs for me. Though, it is a bit annoying when it close an unsaved tab and while it did save, it triggers Unity recompilation making my machine lags a bit.

Perform file operations as you like

VSCode at least have mass-rename or separate class to a new file, where it talks properly with Omnisharp and maintain its sanity. However there are limits. You cannot just new C# file or rename it in project panel in VSCode and have that file works flawlessly until you Alt+Tab 2 times to Unity and back forcing it to recompile, include the file in the C# project, then finally Omnisharp kind of "restart" and know what to do.

As expect of a more IDE-like Rider, you can new file and move file around as much as you like without switching to Unity and ReSharper still works. This is quite huge as in Unity these operation causes a spinning compile wheel of doom, followed by one long freeze before and after. It maybe well over half a minute each time.

Also you could do it all while the file is unsaved (dirty). VSCode Omnisharp often fail randomly in on some refactor commands if you didn't save the file or sometimes, wait for the resulting compile to finish first . I noticed that Rider never fails. Splitting files, symbol renames, dragging the files to other folders like crazy, while unsaved. It always work!

Here's what usually happen when you delete just 1 file in VSCode's Explorer panel. That file is empty because I just refactored things out of it.

How to fix it

And sometimes this doesn't work until you restart the VSCode, with a random combination of restarting Unity or press Open C# Project in Unity after cleaning up all sln and csproj. File operation in VSCode with Omnisharp is just too brittle.

Edit : Something like this wouldn't resolve no matter how you restart Unity or VSCode or Omnisharp, sometimes restarting the computer helps, but I would rather pay then dealing with Omnisharp's tantrum... VSCode is a good editor as long as it doesn't touch Omnisharp.

Recursive error indicator

At first I hate it, but now I love it. When you perform some manual refactoring that automated tools couldn't handle, or even some arbitrary edit, often times you are partly aware that something should break after doing this. Therefore you want to fix those next. Often I don't even want to read the error because I know it gonna error, I want to see where. And the way to do that is to double click follow the error anyways though I don't want to read them.

Usually I have to "Alt+Tab x2" to nudge Unity to recompile and update and produce a new error. But in Rider you see red squiggle appearing recursively to the outer folder what went wrong because of it, without reading the error log. Reading takes time, but you just want to know where quickly and when you see the code you may know what to fix even before reading what the error has to say.

It also applies to place like Search Anything. This is nice as most of the time that is probably the file I want to go.

Find usage : Write access

One extremely valuable feature in Rider not in VSCode, is the Find Usages has category based on read or write. Usually the source of problem in your test where you read, is of course to find the places where it was written. I usually have to look for = sign in VSCode manually or include that in a project wide search. This is very convenient.

Unit testing

You can run Unity tests from Rider. You can only run pure NUnit test in VSCode.

It seems Rider wins but actually no one wins beccaues it is SO SLOW! I would rather double click the one in Unity. It is so slow I got enough time to casually screenshot the "Pending" state of some unit tests which should be lightning fast.

There is a nice button to click on the left of test method so you can run that test, similar to VSCode but it works with Unity. However, it is SLOW so I would rather Alt+Tab to run it in Unity anyways.

Tracepoint (breakpoint that logs instead of stopping program) didn't link to Unity's Console. Also there is a questionable auto complete in here, the eight you see is a valid log because I overridden ToString of it. However the auto complete randomly suggest things not depending on the current scope.

The output appears here in "Debug Output" panel. But it is often flooded with other messages. Ideally I want to see the log in Unity and not here.

Generate equality members

Implementing IEquatable maybe more required than ever for Unity DOTS. This is a very welcome feature in ReSharper that is not available in Omnisharp. For example in some place like ISharedComponentData, ECS library may need your help to judge what is equal and what is not.

You are then present with a dialog box that you can manually choose which values matters in an equality test.

Generate relational members

IComparable is no less important than IEquatable.  It is already used in multiple places in Unity ECS. For example sorting. NativeArray<T> or NativeArraySharedValues<T> could sort if T implements IComparable. In ECS we cannot ensure order of entities coming out from database. Some algorithm sometimes need sorting.

And when you implement IComparable, you remember that "compare this first then if it is equal, see that next and so on." tedious pattern. The command Generate relational members could do it for you in an order you want.

If you add more members and want to take them in account, you can delete the CompareTo method then use the same command again.

Generate dispose pattern

This is equally useful in Unity DOTS where you manage your own memory. It scans all your IDisposable and DOTS follows them.

Generate switch labels

Nice. In DOTS, switch casing on enum is preferred for high performance jump table generated in assembly.

Overloaded operator coloring

In Rider you can see an operator with custom behaviour as differently colored by the color theme. Plus you can also use go to definition on the operator. This above example highlights that it is int4 SIMD operation from Mathematics library, not just C# built-in addition.

Local/internal UPM workflow

I have already highlighted how important you should UPM your own project even for those you not intended to open source.

In VSCode, your project is a folder. When you follow a code into your own UPM package, Omnisharp is able to do so because it ask .csproj about them. And you can also edit the file if that UPM is on local.

In Rider you can do the same, except you can see the project tree of that package. Because Rider knows Unity! A folder with arrow and a box is local UPM.

I think this is nice because in VSCode I was limited to use Go To Definition to go to package's file and modify, I was not allowed to freely browse any other nearby files in the package and must find a way to other files by Go To Definition. It will not be highlighted in the project panel either because you are now out of your project. Rider make it so all packages (non-read only) feels like a part of your project, just like in Unity's project panel.

Easy to UPM your game

By extension of this, you can drag any file to the UPM folder while editing code. You know how painful it is to move file around in Unity. Every little touch cause the spinner of doom. Editing asmdef even display a dialog preventing you from doing anything in the meantime. (Though even if you could, the editor lag so bad you cannot click and drag anymore file anyways.)

Auto refactor works. Renaming things in the UPM package from your main project works and updates your main project too. Overall this is the key feature to modular and testable game code. (You can have an another Rider instance that is opening that UPM as a main package too, though you can edit your package from your main game just as easily. This is not the casse with VSCode.)

Breakpoint vomiting values

I really like this polish in Rider. When a breakpoint is hit, you see each line vomit out all of its possible innards in code comment color without even hovering a mouse and check on the stack list. Therefore it could work well in a code that you "chop" to multiple lines.

This helps greatly to understand the surrounding even the one I didn't intend to check on, but ended up being where the problem was propagated. I had fun with this feature.

It really helps too that the returned value is at the first in list, and it turns orange if there is any change compared to previous break. I could glance and see everything without tediously register each variable for view or fumble with the list below. It's right there in the code.

Documentation auto complete

While it is also possible in VSCode via plugins to get /// to become summary, and also possible in VSCode to get autocomplete inside the "" part of see cref, and it is also possible in VSCode to rename all the way to documentation, it is not possible to auto complete the see cref itself while it is possible in Rider. Small margin of victory but still, nice.

*If Rider team is somehow reading this, I would lose my mind if I could highlight lines in summary  and make it go to <remarks> section via the cleanup menu!

Cutting comment to a new line

I was surprised by this polish also. If you press enter while in the middle of any comment, the new line will be prepended // to be a comment also. Of course when I do this I don't intend to type an actual code in the next line, it is 100% better than not doing it. I didn't know I need it before. It doesn't affect pressing enter at the end of line, or using o key in Vim emulation.

And if the next line has some spaces after // it would be formatted the same way. Great!

Almost ideal Import Missing Reference

This function is very important in VSCode, as I code more properly with namespace, with asmdef and finally with UPM, it adds some hassle of importing things into scope. Luckily I can always do this to resolve them.

In VSCode if you didn't have a reference in your asmdef then Omnisharp cannot resolve it for you. For example, DefaultWorldInitialization is currently red. VSCode cannot know that this particular class is in Entities.Hybrid assembly because you didn't link the asmdef yet. You go link it because you know, then it could help.

In Rider it is a bit smarter. It seems to know Unity to the level that it knows the class from packages linked to your project manifest but not yet to this particular asmdef. But even though the completion works and using was added to the head, it is still unusable because it cannot go to your asmdef file and add missing cross- asmdef reference for you. Almost perfect!

ReSharper is more stable than Omnisharp

You know in VSCode when you do something too "outrageous", it feel like Omnisharp crashed and stopped being smart. When you check the Omnisharp log in the popup console, you will see some errors there but Omnisharp will not recover on its own.

This is solvable with "Restart Omnisharp" command which you will have to wait about an equal startup time of typical IDE like Rider. It is just VSCode that startup fast, not Omnisharp. (depending on project)

I sometimes see Rider goes all red too, but after a few moments it seems to be able to get a hold of itself fast. Granted this cause some performance hit but still better than having to restart the language engine often.

I suspect this "goes crazy" moment is when Unity decided to flip the table and recompile too many links (in not an incremental way, etc.) and Rider/ReSharper handles this more gracefully.

One backspace to bring up to the previous line

When I would like to format the code so it go back to the end of previous line, I think there is no good Vim commands to do this fast enough other than cut and paste at the end of previous line. In Rider, pressing only 1 backspace at the beginning of the line for these 2 cases will bring it up, given that there are only empty spaces to be deleted.

Search Anything includes class/struct

It maybe a practice to separate class and structs to its own file. But in Unity Entities you probably have a LOT (100-200) of tag components used liberally, or a component with very little content (it is common for a component to have just 1-2 fields) which you ended up grouped together in a file, or even in the system file (which may make sense if you want it to be used by . notation after system name, like ISystemStateComponentData).

You then remember the struct name because you work with them always, but forgot what is the class name. Many times I have to find an instance somewhere just so I could use Go To Definition to go to it without knowing file's name.

In VSCode, class search only applies to the currently working file. In Rider you can type the class/struct name you want and it will go to the correct file. Unexpectedly convenient. I really miss this when going back to VSCode, it is difficult to remember which file I tucked that in. Sometimes the file was named exclusively, sometimes the file was named as one of the struct in there that I think is the "boss" of all other structs.

Also, if the class or struct is named the same but in different namespace, it could be easily discernable with the (in ...) followed the entry.

Search Anything includes methods

It means any method in any file.. so it really is "search anything". Why this matters? Because Unity's Test Runner has this annoying workflow where you have nowhere to click to go see your failing tests.

Because the test name is method's name, you can type it in search box and go to it regardless of its file. Note that there is no mention of file name in the Test Runner dialog. It is just namespace, class name, and finally method's name. Being able to go directly to the method is nice. But it would be nicer if the Test Runner failing message turns blue and let me click it..

Autocomplete virtual/abstract methods

This is one thing I thought VSCode Omnisharp could, but it couldn't! In C#, one of the pain point is to type matching_accessor override ExactMethodName(SameType anyNameButYouRatherWantTheSame) correctly. Editor function should help with this chore. Unity was crazy about magic methods like Update() for quite sometime, but now the direction is going to the righteous override path in JobComponentSystem of ECS, that make it more verbose to type.

Actually I remembered Omnisharp could with some difficult condition that it is not so useful. The criteria seems to be you having to type all the way to protected override then some characters, or something? Then the popup finally appears. Also see this issue :

https://github.com/OmniSharp/omnisharp-vscode/issues/1044

In ReSharper, it works as expected. I can immediately type the method name and they appears. On accepting the suggestion, base.ThatMethod() is automatically added, an another pain point that C# didn't force overrides to also call the base, but often you want it to that you ended up making a common routine on the base disappear. (Luckily in ECS there is nothing at the base.. yet.)

There are quite a lot of override to do in ECS to properly optimize the system. (Query ceremony, pre-allocated persistent native array for reuse, etc.) This is very useful.

Junk entries in VSCode

In Go To function of VSCode, often I would see an entry that no longer works. Refreshing these search histories is possible, but in Rider unusable entries are never there. (But of course the performance is also less snappy.)

In Rider one thing I like is that when performing project wide search, when I check on each one and fix it, the "baked" search result will update accordingly to INVALID. This is a good middle ground between re-search and take performance hit or just left them be. In VSCode, the entry didn't change at all, and clicking on them will now go to random line that the search result was there.

Editor attaching / breakpoint

In VSCode, I feel like sometimes I could get the breakpoint to activate but most of the time I cannot. I don't know an exact criteria, sometimes I have to restart Unity editor or VSCode and attach in a specific sequence.

Of course I have this on when I would like to use breakpoint.

In ECS, it is quite important for unit test to use breakpoint where we couldn't use Entity Debugger. Usually you are questioned by how the system did run but didn't perform expected task.

In Rider editor attaching always work. I don't know what is the problem with VSCode but it just works in Rider. The attaching process is quite laggy, but as long as it works it pays off when you managed to find the bug.

Also with Burst off, the breakpoint even hit in the job code as well. I can hot swap Burst compilation while attaching and let the breakpoint work.

In VSCode, when trying to attach the editor usually even after I got it to attach and break properly :

• Doing something "too outrageous" would make the editor attaching lose its mood and stop breaking at all breakpoints.
• Sometimes it freezes Unity and need to restart both VSCode and Unity altogether. I find it often happen if attempt to attach while in play mode. (In Rider, I could attach/detach at any moment.)

Tracepoints / Logpoints

There is this practice of spraying log messages and just let the code run through them in order go get a grip about the situation. It may sounds rough but many times it is better than breakpoints because you can observe "from the top" order, patterns, and their frequency that would ultimately leads you to the solution why the test is not what you expected.

You may spray Debug.Log all over and remove them, which works when compile speed is fast. But it is not so practical to probe different place rapidly. Also in ECS I can't use Debug.Log then forget to comment it out, since Burst will pick it up and complain. Start using breakpoints/logpoints is crucial to ECS development than ever.

So let's use a proper function in the editor. VSCode has a Logpoint feature for this, and equally in Rider, you can turn off Suspend and then turn on Log : Breakpoint Hit message.

Rider wins because :

• The attach works 100% that would allow me to use the feature in the first place.
• You can log "nothing" when you don't know what to type, it will appear as a clickable link that jumps to that line of code. (As seen in the image, you can click any purple text besides "Breakpoint reached") This is very useful.

Run execution to here

I think this is an another killer feature. Often the break point is not quite right. Repeatedly press step forward takes time. Placing a breakpoint far ahead and resume execution works, but I have to remove it immediately after because that's kinda temporary breakpoint. "Run execution to here" solve this problem more directly. And the button even appears on the line you clicked.

Fine tuning color theme

No theme is made just for you. While browsing themes you may find color palette you finally like. But maybe that red was too dark, maybe you like that green more flashy or more pastel. Maybe everything was perfect except they make method argument too colorful and it spread to an entire method since you use the argument everywhere.

In Rider, other Preferences maybe a bit bloated, but they have a very good theme editor where you could exactly pinpoint what would you like to change by clicking the displayed bits of sample text in the box below. Also it supports inheriting in an easy to understand way. The only improvement I want is that they could add an Apply button where I see my real code behind the dialog updates accordingly.

That was my adjustment to Rainglow's Zacks theme, which I like the color already except the red looks too much like error and purple requires too much attention to read so I made them lighter. Also the method argument was green, the same color as class name. Everything turned green in a method where I heavily use the passed in argument, and I don't like it. So I make the ( parameter ) you see above a cream color instead. It is close to white, but just enough so I could see what came from the top of method. Here's an original theme :

In VSCode, to further customize a theme further one need to debug TextMate scope.

Then according to the returned score (like storage.type.cs here) you can override the color of the theme.

It is much more involving, but also it allows more fine grained adjustment. For example, it is impossible to color the < > in Rider. In Unity ECS, there are so many < > that I would like to make them a bit more stand out/more subdued. In VSCode, it has this puctuation.definition.typeparameters.end.cs that allow it to be themed.

Rearrange method signature

You can safely rearrange signature in a way that everything else updates accordingly.

You may think this is such an uncommon issue, but in Unity ECS, static method is going to be a very good way of sharing code between job functions which Burst could treat it as a part of code of each individul jobs. Previously we rely on OOP inheritance to reuse code.

This requires migrating a lot of things via argument so that static could work on what it was given. Able to rearrange them later let you just add required things without much thought at prototyping stage. (The user of the method would get updated arrangement as well, this is the biggest pain point on refactoring utility methods like this.)

Softwrap and line up-down

When situation calls for vertical split while programming, it is important to use softwrap (virutal line break) to be able to read code without scrolling. Vim commands Ctrl+w (window) then v (vertical) does this. Then you can switch between them with Ctrl+w Ctrl+w.

In VSCode, the soft wrapped line is not counted as a new line. So j k commands in Vim emulation will skip to the next real line.

In Rider, they are counted as a new line.

It depends,  but I like the way it works in Rider. Anyways, commands like I will still go back to the real beginning of the real line. (What I wanted)

String split on enter

The above result was made by placing the caret on the middle of string and press enter. The + and all other " appears automatically. This is occasionally neat when you want some wild single line string to be more readable in code. (Unity's [Tooltip] comes to mind.)

Open source license

If you maintain an open source project (you could be already if you UPM your game and some of the package are generic enough) you can apply for ALL product open source license. It could be only used for developing open source projects. But it allows you to use ALL tools. Maybe you can also branch out to non-C# open source projects too.

It lasts 1 year, which you may apply again if the project is still eligible. As you see below, I get only Rider for normal projects, but I can use everything for my open source projects now. Related to Rider, are dotMemory, dotCover and dotTrace. But I have no experience with them yet.

https://www.jetbrains.com/community/opensource/

Extract method

Not sure how the light bulb in VSCode could do because I had never use it, but in Rider it is really good.

I would't care much in OOP, but in data oriented design, we no longer wrap and reuse methods by means of inheritance anymore. (e.g. human has leg and could Walk and so do a dog that has leg, so you write the Walk code once. etc.)

And now one of very good way to reuse code is to just write a static function. Take something in and give out results, functional programming style. Burst code that touch these shared static code will then think that the code "belongs" to itself. (So you get duplicated assembly code in the burst compiled file, but shouldn't matter as long as performance is good.) The other way to share code is to bake some instance method in the struct that could help modify the struct itself.

In this image below, it looks like the TryGetValue below is going according to the above ones. I noticed the pattern and therefore I would like to refactor out the above to also use on the one below.

Refactoring out works on what you highlighted precisely. The following popup then let you customize whether you want return value, or you want ref style. It seems to know what I would like to get from the highlighted code. I was amazed.

This is the FP style that take values in and return the changed value.

As you see when I prefer void as return type, then the generated method has to use ref for the value that connects with what's outside of my highlighed code.

Extract local function

C# has added ability to nest a local function (no even private accessor, it's private in scope and has its own capture rule kinda like lambda). It is a bit weird to write and read and you sometimes don't know where to place them, but still interesting and I would like to practice using it more to create a more "functional" function. A method that contains little pieces of logic assembled.

So, you can highlight and extrace a local function too, not just to the outer method. There is a dialog that ask you where, as local function could be anywhere.

After that dialog, it knows which thing is external to the one you highlight and offer to turn that into a passed-in variable instead of a capture. This is very good to rapidly make a "pure" function out of your code draft. I am always in for things that could raise skill ceiling in programming and this encourages it.

This is also useful for writing tests, as in test you often explicitly perform some sequences before the check. Then you want to do that sequence again to test repeatability, etc. A local function is the most logical way to do it since it does not make sense that other tests could also use this sequence specific for this test.

Final verdict

I used Rider until the last minute, and went back to VSCode for 2-3 days just to make sure how I feel about Rider.

Despite the general impression that Rider is slower, I ended up purchasing 1 year license of it. Here's top things that made me make this decision :

• Editor attaching and breakpoint hitting that always work. This is very crucial in ECS unit testing.
• Finally some new skill ceiling to improve debugging skills because the attach always work. Especially, stop the Debug.Log spraying habit and use logpoints. I would gladly pay so I have something new to level up. (This is exactly how seasonal pass monetization in games works...)
• The editor is resistant to all refactor actions be it from quick fixes popup or by you dragging things in Explorer.
• It let me develop in packages with less friction.
• IdeaVim is generally faster and better, especially how it could come back to the same place after gd into it.
• Go to definition knows how to drill into UPM package source code and not dll version of them.
• No more annoying Omnisharp red squiggles. (And Resharper start up faster than Omnisharp)

I missed these in VSCode :

• More muted color design overall.
• Better Preferences that looked much less bloated.
• Lower battery drain when I am not plugged in.

In this article I will guide you to adopt asmdef and (internal) Unity Package Manager in your existing project. It will be harder than if you do it from the beginning, but that's why I have written this guide. Also it is so that in the future, your new part of code could be in UPM properly for more orderly one-way reference.

This article assume you know basic benefits of it and how it works with folder structure to group your scripts. This article will start by going over some benefits that may not be obvious to you, so that you are motivated to do it.

Benefits

• Compiles faster with the built-in incremental compiler. This is not even its full power, as I heard from the forum that Unity is prepping for no domain reload play mode enter and faster hot reload on script changes. That could be depending on how well you separate asmdef today. (A guess, but likely) Today, it do not affect enter play mode time unfortunately.
• Allows you to name your folder that previously must be named exactly Editor as anything else, with editor asmdef. (But you should name them Editor anyways..) To do this, make sure Any Platform is unchecked, then only Editor is checked for Include Platforms.

• Previously all your Editor folder scripts do not ended up in your game, now it is the same except that they could be separated by dll, decrease compilation speed for even editor code.
• Test assemblies. They have their unique problem. To make an edit mode test assembly, do the same as editor asmdef except check that Test Assemblies box. This is the same as putting tests in the Editor folder.
  However the real benefit is in making the play mode tests. Previously there is a problem that you want to test something in play mode the script must stay out of Editor folder, then they will be included in the game too if not removed manually.
  Now with that Test Assemblies check box plus non-editor setup, you get something usable in play mode and even in real device test but somehow not in the real game build! To get a special behaviour of allowing play mode test in the real build, press this button.

Without asmdef this button is also usable but they will also be in your game for real.

• As a bonus you could rank your script's weight at glance in Library/ScriptAssemblies. I once caught an error here when one of my plugins included a huge baked constants that I should remove.

• Make you an organized, clean coder, since it will not allow you to make messy dependencies. In a way, this is a unit test for code organization.
• asmdef pave way to UPM, which could share code between your projects or even open sourced online. This is the ideal form of module based development, but for starters let's try to segment an already messy game into asmdef without UPM first.
• Will this make your game easier to hack when they could see all your dll separated up nicely? Maybe, but your single dll game is also hackable if the hacker wanted to see your symbols anyways.
• Earn additional income by prototyping a would-be/potential Asset Store items as a package with thier own asmdef in their own project. Field test them in all your real projects easily without copy, with UPM link and asmdef link.

UPM warrants its own topic, which is not the same as asmdef but closely related.

Unity Package Manager is going full asmdef

For those who didn't catch up yet, we used to read Unity version release change log. Now they do it NPM style, each internal team that work on a feature could push an update on their own, each with its own CHANGELOG.md. This is a great initiative! All these fun stuff available to play with. (And more bugs to report!!)

UPM works with package.json at root of the package's folder much like NPM, but it is customary that you should do asmdef also. The official pattern looks like this :

• Company.PackageName : For the main part
• Company.PackageName.Editor : For the editor only part (references the main part)
• Company.PackageName.Editor.Tests : For unit test / edit mode test (references the main part)
• Company.PackageName.Runtime.Tests : For integration test / play mode test (references the main part)

For example, my plugin Introloop looks like this with an additional "Demo" assembly.

Since my demo scenes has some debug scripts to show how things work. When my customer wants to use the plugin, if they adopted asmdef already, they could include only non-demo part to their game. (If they don't, all non-editor asmdef will be referenced like usual) Also it helps sanity check me that I don't use something in the demo from my main part.

I will explain to UPM your own game along the remodeling section. But first let's see some obstacles that you must overcome.

Asmdefs are infectious

Your game completely devoid of asmdef was perfectly fine. But your game with just one asmdef became quite troublesome. (Maybe you just want that test assembly, maybe you want to do it only a little at first)

They are "infectious" (similar to things like async/await programming) that if you don't do it all, you can't do it at all. To see why :

Overviews to keep in mind

• Anything in asmdef are now secluded from the world, where previously it knows everyone. You have to link up asmdef to get it to know each other.
• Anything in asmdef still know all precompiled .dll like before. For example if you have Firebase Unity SDK which consists of closed source code packed in .dll, all your asmdef has access to it. You don't have to link them up. Except one dll ...
• Everything not caught in asmdef will be in the catch-all Assembly-CSharp.dll. This .dll has one big problem : none of your asmdef implicitly know this dll, and cannot explicitly reference it. Not even with Override References. It must be the terminal node of the "reference graph".
• This includes if you decided to write a test in its test assembly while keeping everything else in the game as before (spilled out to catch-all dll) Now turns out the test cannot test anything, since the thing to test cannot be referenced to the test assembly. You face a dilemma because you don't want to ship test code either. Now you must asmdef an entire game, which brings to this article.
• If you check Override References it will remove the mentioned "know every .dll" ability and let you explicitly define each one. The box below will not appear if you didn't check it. "References" in this context meant .dll only, not asmdef.

• The link cannot form any circular dependency. This is the most common roadblock that make you give up on using asmdef and this article will advise how to avoid this.
• This is why UPM package could be 100% asmdef'd and should be, because by nature they are plugins and do not depend on something specific to your game. The reference direction is one way : your project use the package.

Together, it cause trouble like these :

Can't reference Assembly-CSharp.dll problem

You only want to pack up your play mode test code in an asmdef and not touch anything else in the project. But obviously your test code should at least check on something in your game, like if start at this scene and wait 10 seconds it should show this and that.

Sure, you can start a scene with string, and wait, and then use magic method like GameObject.Find to try to blindly auditing the environment without actually what they are. But these tests are brittle and break when you change the scene's content.

You want your test assembly to reference anything else but it is not possible to do it with Assembly-CSharp.dll. Check mate, you delete the asmdef and think this is a waste of time.

The bridge problem

you see some folder that looks self-contained and would be nice to place asmdef on. (For example "TitleScreen") By placing the asmdef on just this folder and let everything else go to Assembly-CSharp.dll, if any of the other scripts has a reference to things inside this TitleScreen folder, you are now out of luck unless you move it to the same asmdef.

What could be these "bridge" things? The most common is something that interconnect scenes. You may have SceneTransitionManager for example, which is like a static hub that was designed that everyone could call and move to the other scene, along with passing some data to the destination scene + clean up. The everyone-could-call part is fine, but if you have something like TitleScreen.options.noIntro = true in your scene transition, you are now shooting yourself with circular dependency.

Then you may think let's just move that into the TitleScreen's asmdef. Now the other screen's asmdef have to link to TitleScreen's asmdef for strange reason that they just want to access the utility. This is what I call "the bridge problem" since the bridge needs to know everyone, and everyone must call the bridge somehow, therefore the dependency is not one way and it prevents us from remodeling into asmdef.

How to fix this problem comes later while we are remodeling together.

The plan

• The most logical unit of asmdef for your game I think is scenes. (depends on game genre still) We will try divide the asmdef equal to your scenes/screens. Like title, mode select, game play, credits, shop, etc. The name will be Company.MyGame.SceneName.
• Plugins + your own multi-project common code should all be thrown away to UPM and 100% wrapped in asmdef. If it errors after you do this, the plugin is coupled to the game and you should not call it a "plugin".
• There is something called Company.MyGame.Core, which ALL scene asmdef could reference but not allowed to reference anyone else except plugins.
• There is something called Company.MyGame.Scripts that try to catch anything else not fallen into "Core" or any of the scenes. This is not allowed to reference any scene assembly, but can reference the "Core".
• When you achieve all these, you will not see Assembly-CSharp.dll. Indicating that Company.MyGame.Scripts had taken place, but this time it removes the "not able to reference Assembly-CSharp.dll problem!

Example references :

The arrow shows explicit reference that must be specified on asmdef. The .dll are implicitly known by everyone.

Step 1 : UPM your Asset Store plugins / .unitypackage you bought

Most developers hadn't put either package.json or even asmdef yet. You could do this like so :

• Make a new Unity project called "My Asset Store Plugins" or something.
• Use Asset Store in the editor to download the plugins.
• Put asmdef in the plugin's folder accordingly.
• Put package.json. Copy the pattern from Unity's official package. The version must be semver compatible (x.y.z)
• Use Package Manager's + button to locate each local package.json as desired from your game project.

This approach make it easy to update these plugins by coming to this "plugin galore" project and press update in Asset Store tab, so it overwrite files in their intended location, then the change will be reflected in ALL your games that use these UPM.

You should not get any errors even if no other part of your game became asmdef yet, since all your things should be in Assembly-CSharp.dll, and this dll knows all  asmdef (including one that came from UPM) and all other dlls. This is why this is a step 1. Go make sure your game compiles now.

For .unitypackage, do the same thing except this time they didn't came from Asset Store, so you could put them wherever (even in a normal folder that is not Unity project! But you need a Unity project to unpack .unitypackage anyways). I put them together in the same "My Asset Store Plugins" project as my Asset Store items.

For example, I was able to UPM the Spine .unitypackage by adding 2 asmdef and 1 package.json :

{
    "name": "com.esotericsoftware.spine",
    "displayName": "Spine",
    "version": "3.7.0",
    "unity": "2019.1",
    "description": "2D animation for games.",
    "keywords": [
        "animation"
    ]
}

Then it will show up :

Some plugin cannot be a package since :

• They try to do something related to their script position, or write something to its folder (bad practice!) in that case you will see some errors as you use them. This doesn't mean you can't put asmdef. For example, I found that I2 Localization as UPM package throws something about writing file to somewhere as I use them. (It compiles) But I am able to put just asmdef on and let it lives in the project. It is still better than nothing, just that if your another project want to use this you must copy, then update on each projects individually.
  

One another instance is Google Play Game Services (GPGS), where I could put asmdef and let it be in my project. But once I tried to do UPM, it complained :

Indicating that the plugin really wants that exactly named "GooglePlayGames" folder cluttered directly in yout Assets. Ugh..

• The plugin contains tons of dll, which are useless to asmdef in the first place. Some example of these are Firebase Unity and Odin Inspector. You must let them sit normally in the project. .dll plugins aren't bad, in fact you are putting asmdef so that they became little .dll. .dll plugins aren't recompiled together with your project, but more difficult to debug.
• They are arranged in strange folder combination. For example has multiple Editor folder sandwiched in multiple subfolder that you think it is a hassle to arrange them and have to do it again on the next update.
• They wants to be in a special folder like Plugins. In this case, since you could have only one Plugins folder in your project you cannot use UPM.
  You could try putting asmdef regardless inside the Plugins folder and if it works, it means it doesn't really need to be in Plugins folder! One example is Maintainer, which is an editor-only plugin. I could left that in Plugins folder in my "My Asset Store Plugins" project, then from my game link to package.json inside that Plugins folder. You should not pull it out of Plugins even if you know they work regardless, since it will be easier to update from Asset Store if you keep the same shape.

Take .meta files with the package!!!

The .meta file contains GUID which actually links things in the scene that use these scripts to the actual script. If some day I moved my Asset Store code somewhere without copying .meta file, I am breaking all my customer's existing projects.

Think of it as the identity/lifeline of each of your file. You can rename the code's file name as long as you also rename the .meta file (this is automatic if done in Unity editor), or else it will destroy the .meta file and generate a new one. This is a serious problem.

The only somewhat negligable case is .meta file of folders. But those are still serializable by something like UnityEngine.Object on your ScriptableObject. It could still disconnect! For example my in-development plugin contains a feature that remembers folder to scan its content. If this folder's .meta file changes it won't be able to locate the same folder since all it did is actually just remembering the GUID, not the actual folder.

Step 2 : UPM your own shared code, internal or not

You may have only 1 game in development now, but as you develop please always try to think "could this feature stand on its own?"

All my plugins Introloop, Native Audio, and Native Touch are all solution to some problems in my game. However I realized they could stand on their own and be reused on my future projects. Right now, that future project turned out to be other people's projects! They are able to be distributed on Asset Store thanks to portability ensured by UPM, plus field tested by them included in all my games with ease.

Even if you aren't going to sell them you still should. For example I have a collection of "fun stuff" called E7.Unity where anything goes. So let's name your thing, probably use namespace practice correctly, and put in those asmdef and package.json.

If your plugin sounded epic enough to be sold on the Asset Store

Put them in its own separated Unity project. Your game project has the priviledge of yoinking it directly locally by locating package.json inside instead of pulling from Asset Store. This way you could run your plugin's test scene in its own project, which is useful to check integrity when upgrading Unity version. Then you could "dogfooding" the plugin with your own game because it is linked via UPM to only you, not your customers.

Native Audio is in its own project, which is sold on the Asset Store. In this case, you should version control the entire project because its for your private use. Then inside it AssetStoreTools is for submitting. Then inside a folder of your plugin could contains package.json and asmdef.

If your plugins aren't epic enough to be sold

You maybe able to use GitHub integration to bring them online! The requirement is that they must be a public repo, so not for those you are going to sell. And also package.json must be at the root.

You can put them together in a new Unity project called "My UPM Packages" or similar. In this case, you should version control each folders in your Assets folder.

Or you could put it in its own project. In this case don't version control from outside of Assets but do it inside.

Put README.md near packages.json and asmdef too. Ok, putting .git there may risk losing the ProjectSettings. But trust me GitHub integration is way cooler.

Either way, when you push them you should get a landing page with package.json visible from the front page together with the README.md. If you could get this, your GitHub package is now UPM compatible. If you put .git outside Assets, you will not get this layout.

https://github.com/5argon/E7Unity
https://github.com/5argon/NotchSolution

To pull, you must add an entry manually (by Unity 2019.1) in manifest.json. The format is a combination of what you put in package.json on the left, then URL on the right. For example :

"com.e7.notch-solution": "git://github.com/5argon/NotchSolution.git"

If you want to pull again it is not automatic. Look at the bottom of manifest.json and remove the package's lock.

Not only it is online and you could share with friends, you could get contributors and pull requests! My Notch Solution which sounded epic but I decided to be not for profit ended up having multiple contributor helping me to fight the notched phone.

From now on starts any new component on UPM

To avoid this hardship of trying to asmdef and UPM existing game, the next "module" should start from UPM and link it to your main project. Great, great benefit of your internal UPM package even the one you didn't plan to share with the world includes :

• Occassionally you upgrade Unity or some important plugins, and now everything turns red. If you develop in UPM, you can open those individually and see if the red errors came from them or not. Keeping your sanity and let you fix part by part. Your game is now a multiple Unity project where other little project is a shell that imports just one internal UPM you have developed.
• The fastest ticket to bug fixes. You can write a self contained unit tests in your UPM package. And when you suspect Unity bugged, that would make your test turn red. Usually you don't want to submit a bug report since you don't want to upload 30 GB of art assets and you got no time to make a reproduce project. But now you can submit your UPM package that would be less than 1MB of pure code, and just tell Unity team to double click on some test and see it goes red. The turnaround time will be impressively fast because they will be happy to fix this self-contained, concise problem, that they have just one goal to make the test go to green again. In summary, it will reduce the hopelessness to wait for bug fixes.
• Each one has its own version control, great for time traveling and experimenting without affecting other modules.

Some example where you should do this. If you are making a button in your game which plays different sound on pressing down and up, a UPM package of this maybe probably too much of a hassle. However if you want to add a "stats and achievements" summary screen to motivate your player in the next update? This kind of thing is ripe for a lot of bugs and you want to make sure just this section works correctly for any data thrown at it. This would be a good candidate for internal, code-only UPM.

Results of Step 1 and 2

You have cleared up stuff from your Assets to Packages down below, even if your main game hadn't used any asmdef yet. Save for some pesky plugins that are either dlls or immovable and must stay there, they will ended up in Assembly-CSharp.dll and can't be helped.

Let's recap that we just did the green part on the right here. All your scripts are still in Assembly-CSharp.dll together with non-UPMable scripts, which knows asmdef coming from UPM and from "plugin that could asmdef but couldn't UPM" in the project, implicitly. That's why I didn't draw the arrow from Assembly-CSharp.dll to UPM packages, which is for explicit references.

The hard work is coming next, plugins are separable by their nature. Not the same for your game scripts.

Step 3 : Determine the Core

Setup your folder like this.

The Assemblies is the catching net with Scripts assembly, no other scripts in the project may be outside of Assemblies, but ideally in the end you should not let anything escaped from its own folder to this Scripts assembly! Instead, look at TitleScreen. Everything will be caught in its own assembly. But right now is still not the end though, you will gradually work on the transition to asmdef this way.

Right now only my TitleScreen falls into its Title assembly, and all other scenes are at the Scripts catch-all assembly. The Scripts serves one more purpose, unlike letting them go to Assembly-CSharp.dll this one is referencable. Even if in the end you should have nothing in Scripts, right now you solved one problem : your play mode test assembly could now test on all scenes by linking that asmdef to Scripts, even though you just started migrating just your title scene to asmdef.

The Core folder is inside this Assemblies folder, but you should view it as the outmost! Since we made a rule that it couldn't reference anyone, not even Scripts. (But it could go to plugins UPM asmdef)

Now, you have to solve this problem : Make this 3 asmdef works SceneName Scripts Core. You will immediately see errors if something in the Core goes the opposite way. So it's time to refactor your code to determine what could be in the Core as much as possible. And this involves "the bridge problem" earlier.

How to fix the bridge problem

Let the bridge contains a part of everyone instead, and everyone use this data pool. The bridge still didn't reference anyone but somehow magically knows who is going to come. Then everyone use the bridge.

For example if this problematic bridge is the ChangeSceneManger which was doing load scene with scene name defined in the now-separated assembly. (e.g. the manager knows how to go to Title or ModeSelect, but now the scene name are inaccessible since they go to those assembly and one way reference is preventing us.) Instead, you move just those scene's name to the bridge. It feels wrong, but fast to implement.

This is an example of mine, it has superpower to define a placeholder variable for all the scenes to write to, but no, it do not reference any of these scenes.  It is those scene asmdef that should reference this bridge code. Let's say we have cheated the dependency system. Title scene knows how to look at its own section and do what it should. The bridge assembly can set things into this part without knowing what the Title assembly will do about them.

using System;

public static class SceneOptions
{
    [Serializable]
    public struct Title
    {
        public enum TitleMode
        {
            WithoutIntro,
            WithIntro,
            SkipToModeSelect
        }
        public TitleMode titleMode;
    }

    [Serializable]
    public struct Result
    {
        int p1Score;
        int p2Score;
        bool challengeCleared;
        bool withoutScore;
    }
}

It is a price to pay for remodeling a project for asmdef + UPM deep into the project.