If you want to game jam in Unity DOTS, here's what you probably want to know...

DOTS Challenge Game Jam Tips.md

DOTS Challenge Game Jam 2020 Tips

I have done more weekend game jams using DOTS than my better hand can count. Some of them were alright. Most weren’t too pretty. I’ve learned some things. There’s a lot of early pitfalls that can doom a project from the start. Here’s how you can avoid the worst of them.

Install Unity

Use Unity 2020.1.xf1. Pretty much any x version will work. I’m using 2020.1.7f1 currently.

By default if you mash through prompts you might install Unity 2019.4. You will be using older DOTS versions if you decide to use 2019.4.

To ECS or not to ECS?

The first thing you need to ask yourself is whether you want to try learning ECS or just stick to jobs and Burst.

It is ok to skip ECS if you just want to focus on the non-preview tech. But actually push that tech to do things that normal C# code couldn’t. The infamous Boat Attack demo uses jobs and Burst for the water simulation. I once represented 100,000 virtual objects with 1000 real GameObjects by using culling and distance-based prioritization so that a large scene was full of these objects everywhere you looked. There’s stuff you can do with animated textures, with particles, with raycast, ect. Push some boundaries!

If you do decide to use ECS, well, that’s what the rest of these tips are for!

Project Structure

Open Project Settings and click the Editor tab on the left panel. Scroll down to Enter Play Mode Settings and click the Enter Play Mode Options (Experimental) and uncheck all the boxes underneath it.

Open up the Package Manager. The following DOTS packages are hidden, but you can add them by clicking the plus sign in the top left and choosing Add package from git URL although you will not be entering a git URL. Instead, you add some of the following:

• com.unity.collections

• com.unity.jobs

• com.unity.mathematics

• com.unity.burst

• com.unity.entities

• com.unity.rendering.hybrid

• com.unity.physics

• com.havok.physics

• com.unity.dataflowgraph

• com.unity.animation

• com.unity.timeline.dots

• com.unity.audio.dspgraph

Hybrid Renderer V1 or V2?

Yes, there are two versions of the Hybrid Renderer. They both come in the same package.

Hybrid Renderer V1 works really well with static objects (using Static Optimize Entity scripts) but starts to chew up the main thread once you have 20,000 dynamic entities or so. Use it with Universal Render Pipeline version 8.2. Lighting might be a little inconsistent between GameObjects and Entities and I don’t think more than the main light is supported.

Hybrid Renderer V2 handles many dynamic objects well. It plays really nicely with High Definition Render Pipeline 9.0 preview (A 9.0 version is required, I have tested both preview 14 and the latest although you cannot migrate between the two). Multiple lights, sky illumination, and motion vectors all work. To turn on V2, add ENABLE_HYBRID_RENDERER_V2 to your scripting define symbols.

I can’t vouch for the other combinations.

Getting the right platforms

This one is tricky, because these rarely install correctly. You want the following packages:

• com.unity.platforms

• com.unity.platforms.desktop

• com.unity.platforms.windows

You want version 0.7 of all of these. And you probably want to pick the same preview version. I use preview.8. A lot of people complain about using the latest 0.8 versions and having problems.

Having the right game idea

DOTS is not very feature-rich at the moment. You are going to want to think simpler in terms of gameplay and find the fun factor that plays well with a large chaotic number of a simple thing.

• If you use Physics, plan on not modifying or scaling colliders at runtime.

• If you use Physics, you can’t make a rigidbody a child of anything. A rigidbody GameObject will unparent itself when converted to an entity.

• Animation is in a difficult-to-learn highly-experimental state right now. Probably avoid it. Use rigid objects like vehicles instead.

• The Hybrid Renderer combined with Shader Graph has this cool mechanism for instanced properties. You can cheaply modify these properties every frame for many entities. Use this to compensate for the lack of animation support.

• Audio support in ECS is not good atm. Use classical GameObjects for this and try to keep as many sounds attached to the player or camera as you can. Ignoring sound other than music is not a terrible strategy. If you feel brave you can try playing around with dspgraph, but that’s not easy in the short timeframe.

• Plan on having a single scene. Entities don’t disappear when you switch scenes. If you really want scene switching where entities behave like GameObjects, talk to me as I have a solution but it has some additional project constraints that make it not for everyone.

• Do not use shaders from the Asset Store unless they are Shader Graph shaders you can modify.

ECS Quirks and Jamming Tips

• In GameObjects, you can tweak inspector properties in play mode. In ECS, you can’t, because the GameObjects stop existing after conversion. There is this concept of “separating authoring data from runtime data”. This is very powerful as it gives programmers the chance to sanity check and clean up the data before it hits runtime, but it is a little cumbersome for game jams and rapid prototyping.

• One of the first things you will probably want to do is spawn a bunch of entities randomly placed in a system. Use Unity.Mathematics.Random and do the random generation of positions and rotations in a single-threaded job. It is totally normal if this takes you a day or two to get right.

• It is ok to use mega systems in a game jam. Some of my best DOTS game jams only had 2-4 custom systems. I just let them grow. Don’t waste to much time architecting. For the scope of game in a game jam, it doesn’t matter as much thanks to the DOD API.

• It is ok to have fewer mega components in a game jam. You really have to have a lot of entities for the data layout to become a problem. Keep the number of components down to something maintainable.

• It is ok to use .Run() on jobs and lambdas in a game jam. The main speedup factor here is Burst. Don’t prematurely optimize.

• In ECS, the transforms are local space and the world space transform data is in the LocalToWorld component which updates infrequently. You can tell it to update by calling World.GetExistingSystem<TransformSystemGroup>().Update().

• To safely get the rotation of a LocalToWorld ltw, use quaternion.LookRotationSafe(ltw.Forward, ltw.Up). The Rotation property is broken in some cases.

• To attach the camera to an entity, you can make the camera a pure entity by adding a ConvertToEntity script set to Convert and Destroy and also adding the Scripting Define Symbol: HYBRID_ENTITIES_CAMERA_CONVERSION, but DO NOT put the camera in a subscene.

• If a tutorial you see uses JobComponentSystem the tutorial is a bit dated. Always use SystemBase instead. It takes the place of both ComponentSystem and JobComponentSystem and is more stable.