Search Unity

  1. Unity 6 Preview is now available. To find out what's new, have a look at our Unity 6 Preview blog post.
    Dismiss Notice
  2. Unity is excited to announce that we will be collaborating with TheXPlace for a summer game jam from June 13 - June 19. Learn more.
    Dismiss Notice

Official DOTS Guide - tutorials and more

Discussion in 'Entity Component System' started by Fabrice_Lete, Sep 29, 2022.

  1. Fabrice_Lete

    Fabrice_Lete

    Unity Technologies

    Joined:
    May 5, 2018
    Posts:
    55
    Hi everyone! We have just published a set of reference material to help you get started with DOTS, and ECS in particular. You’ll find there:
    • A summary and video overview of important ECS concepts
    • A simple tutorial to learn the basics of using ECS and the Job System
    • A set of cheat sheets across API topics
    https://github.com/Unity-Technologies/EntityComponentSystemSamples/#learning-dots

    This is the first release of this material, so we are eager to read your thoughts. Please use this thread to share any feedback you have on how to improve that content.
     
    Last edited by a moderator: Dec 21, 2022
    yuliyF, Mj-Kkaya, TP-Fab and 31 others like this.
  2. Trindenberg

    Trindenberg

    Joined:
    Dec 3, 2017
    Posts:
    416
    Very impressive, neat and tidy setup, helped to understand the different aspects. Hope there will be more guides on the different windows etc.

    Did however have to get through about 5 Unity reloads (build system error, something to do with saving code VS/recompile), and finally out of memory crash (32GB) blackscreened. Oddly I can no longer load the project, it just keeps loading Application.UpdateScene. Probably need a computer restart.

    Internal: JobTempAlloc has allocations that are more than the maximum lifespan of 4 frames old - this is not allowed and likely a leak

    Internal: deleting an allocation that is older than its permitted lifetime of 4 frames (age = 6)
    UnityEngine.GUIUtility:processEvent (int,intptr,bool&)

    I put this down to the Editor being beta though (b9), or something to do with Burst (1.7.4).
     
  3. Trindenberg

    Trindenberg

    Joined:
    Dec 3, 2017
    Posts:
    416
    Restarted and stable so far, and still impressive. Was hoping to build, is that a no go on IL2CPP atm, or am I missing a setting in Build Configuration?

    Assembly-CSharp.cpp(11739):
    error C2664: 'float fmodf(float,float)': cannot convert argument 1 from 'RuntimeObject *' to 'float'
    error C2660: 'Il2CppCodeGenWriteBarrier': function does not take 1 arguments
    error C2664: 'Color_tD001788D726C3A7F1379BEED0260B9591F440C1F Color_HSVToRGB_m1E66966AAB74D56DB4D339B65E60E2AF435C8105_inline(float,float,float,const RuntimeMethod *)': cannot convert argument 1 from 'String_t *' to 'float'
     
  4. dannyalgorithmic, owlrazum and bb8_1 like this.
  5. Kichang-Kim

    Kichang-Kim

    Joined:
    Oct 19, 2010
    Posts:
    1,019
    https://github.com/Unity-Technologi.../DOTS_Guide/intro/intro-entities.md#systemapi
    Document said SystemAPI can only be used with ISystem or IJobEntity, but package documentation shows that SystemAPI is used in SystemBase.

    https://docs.unity3d.com/Packages/com.unity.entities@1.0/manual/systems-systembase.html

    Code (CSharp):
    1. [RequireMatchingQueriesForUpdate]
    2. public partial class ECSSystem : SystemBase
    3. {
    4.     protected override void OnUpdate()
    5.     {
    6.         // Local variable captured in ForEach
    7.         float dT = SystemAPI.Time.DeltaTime;
    8.  
    9.         Entities
    10.             .WithName("Update_Displacement")
    11.             .ForEach(
    12.                 (ref Position position, in Velocity velocity) =>
    13.                 {
    14.                     position = new Position()
    15.                     {
    16.                         Value = position.Value + velocity.Value * dT
    17.                     };
    18.                 }
    19.             )
    20.             .ScheduleParallel();
    21.     }
    22. }
    23.  
    24.  
    What is correct? can I use SystemAPI on both SystemBase and ISystem? or ISystem only?
     
    DonPuno likes this.
  6. Fabrice_Lete

    Fabrice_Lete

    Unity Technologies

    Joined:
    May 5, 2018
    Posts:
    55
    There are definitely some issues in this experimental release, I don't think anything you encountered there is specific to the tutorial and are already tracked (check the list of know issues in the main announcement post). Those particular temp allocation leak reports should normally be false positives.
     
    DonPuno likes this.
  7. Fabrice_Lete

    Fabrice_Lete

    Unity Technologies

    Joined:
    May 5, 2018
    Posts:
    55
    This might be related to this know issue about IL2CPP builds, did you try with this setting?
    • IL2CPP builds require building with the IL2CPP code generation option “faster (smaller) builds” currently.
     
  8. Fabrice_Lete

    Fabrice_Lete

    Unity Technologies

    Joined:
    May 5, 2018
    Posts:
    55
    Ah, one of the two most frequent problems in programming: invalid pointers, division by zero, and off by one errors.

    In this particular case, I think the intent was to discuss TempJob being replaced by the UpdateAllocator and that missing bit slipped through.

    Thanks for reporting this! We'll get that fixed, and more documentation about memory allocators will be published later.
     
    owlrazum, Lurking-Ninja and Anthiese like this.
  9. Fabrice_Lete

    Fabrice_Lete

    Unity Technologies

    Joined:
    May 5, 2018
    Posts:
    55
    SystemAPI works in SystemBase just fine, the DOTS guide is wrong. Thanks for spotting the error! We'll get that fixed.
     
    DonPuno, bb8_1 and Anthiese like this.
  10. Trindenberg

    Trindenberg

    Joined:
    Dec 3, 2017
    Posts:
    416
    I've tried a normal build (now using Smaller Builds) also using a build configuration which doesn't have a choice. Furthest I get is, cannot find mspdcore.dll. When I updated to VS2022 I deleted VS2019 not sure if that has anything to do with it. I'll try adding some more build tools in VS feel that something is missing as unable to find manually.
     
  11. JohngUK

    JohngUK

    Joined:
    Aug 8, 2019
    Posts:
    11
    Finding the material really useful to 'get my head round' DOTS and am enjoying the process. The organisation of scripts into different DOTS directories by concepts is helpful. The step by step, illustrate one concept at a time approach works for me, as usually I drown in detail. I am using this tutorial to establish my workflow for creating projects with DOTS, so a template for the 'correct' way of creating and organising a DOTS project would be useful.
     
    Last edited: Oct 4, 2022
  12. Occuros

    Occuros

    Joined:
    Sep 4, 2018
    Posts:
    305
    Fantastic job with the guide, especially the example of the ecs tutorial was a very nice and good way to showcase ecs.

    Also great to have it hosted on GitHub as it works really well on all devices to look at the documentation.

    I’m hoping for more guides in a similar style for the other packages and more advanced topics.

    Keep up the great work!
     
    owlrazum, DonPuno and PolarTron like this.
  13. gg_michael

    gg_michael

    Joined:
    Sep 24, 2012
    Posts:
    73
    The guide is great, excellent and clear way to learn about the fundamental concepts.

    What is really needed, and I'm sure you know this, is a series to walk through the practical steps of integrating these concepts into a game. Roll-a-ball but for DOTS, or something. The tech is not settled so I get that this release cycle is aimed for established devs who presumably can figure out that stuff on their own. But the true herald of the DOTS era will be when we can see and follow along with best-practice implementation to create a functional DOTS game.

    The guide is great though!
     
    Garrettec, OldMage and Trindenberg like this.
  14. Trindenberg

    Trindenberg

    Joined:
    Dec 3, 2017
    Posts:
    416
    I think is important to have guides and tutorial around it on full release so that users who might actively promote it can more easily get to love it and make it popular. Maybe also some basic useable templates to start people off. I like the idea of visual scripting and high performance which tend to be opposite ends of the spectrum.
     
    Garrettec likes this.
  15. JohngUK

    JohngUK

    Joined:
    Aug 8, 2019
    Posts:
    11
    There is a slight ambiguity in:
    Modify the contents of the file named "TurretShootingSystem.cs" in the folder "Scripts/Systems" as follows:

    +// Requiring the Shooting tag component effectively prevents this job from running
    +// for the tanks which are in the safe zone.
    +[WithAll(typeof(Shooting))]
    [BurstCompile]

    Being skilled in the art of getting things slightly wrong, I inserted the modification before the first instance of [BurstCompile]. Of course the tanks were not inhibited from shooting in the safe zone. It took me two iterations of creating the project to realize that what is meant (when I read the instructions carefully) is to insert the code before the second instance of [BurstCompile]. But thanks for this excellent example - I am enjoying learning ECS.
     
  16. Spy-Master

    Spy-Master

    Joined:
    Aug 4, 2022
    Posts:
    764
    Are you talking about step 4 of this part?
    I wouldn't exactly say there's ambiguity here, the context provided below that part of code - the whole TurretShoot job, actually - should be sufficient. It's totally understandable to make mistakes like this when you're over-eager (that's usually a good state of mind).
     
    JohngUK likes this.
  17. JohngUK

    JohngUK

    Joined:
    Aug 8, 2019
    Posts:
    11
    I agree and perhaps it is the best way to learn. However, if some of the original context before [BurstCompile] had been provided, then there would have been no ambiguity, and my 'digital correlator' would have operated correctly, even when operating at zero lines of look-ahead awareness.
     
  18. sivabalan93

    sivabalan93

    Joined:
    Dec 5, 2017
    Posts:
    5
    Is DOTS and ECS supported in WebGL platform?
     
  19. WAYNGames

    WAYNGames

    Joined:
    Mar 16, 2019
    Posts:
    1,003
    @Fabrice_Lete
    Can you add a section using dynamic buffer ?
    Something like I do with my DOTS training series where entities follow a path defined by a dynamic buffer ?
     
    chadfranklin47 likes this.
  20. esainton

    esainton

    Joined:
    Nov 16, 2013
    Posts:
    1
    Hi.

    You asked for feedback. I'm still reading it through and testing. While it's dense (and the initial setup not as smooth as I wished, but ti's more my fault and configuration from unity hub fault), the whole is very digest and informative.

    I'm currently doing the ecs tutorial : https://github.com/Unity-Technologi...emSamples/tree/master/DOTS_Guide/ecs_tutorial

    And on point 12, in the note it's mentioned that the following step would use ComponentDataFromEntity with a link to the doc. The doc points to the correct method, but this one is documented as Obsolete, and indeed in the following code the method is not used. Reading the comment from the code and the note text I believe it should be updated (in the doc) to ComponentLookup?
    If this is the case it would be great as well in the documentation of ComponentDataFromEntity to have a link mentioning that the correct replacement for this obsolete method is ComponentLookup.

    Except for that, so far so good, really excellent tutorial!

    Thanks
     
  21. IsaacsUnity

    IsaacsUnity

    Unity Technologies

    Joined:
    Mar 1, 2022
    Posts:
    94
    Thanks for the question! You can use the Entities package and build toward the WebGL platform. We're actively working on a small sample to show how users can achieve this in our next release.
     
    Deleted User, bb8_1, JesOb and 2 others like this.
  22. whitefenix

    whitefenix

    Joined:
    Feb 3, 2015
    Posts:
    1
    Hey, thanks for the guide, I found it very helpful :)

    Ran into a problem on the ECS tutorial (the colored tanks) at https://github.com/Unity-Technologi...blob/master/DOTS_Guide/ecs_tutorial/README.md

    The "shooting" component is always enabled, even when tanks are in the safe zone, which makes them always shoot.

    I tried setting it to false directly, as shown here:

    upload_2022-11-2_18-14-39.png

    But the tanks still shoot. I can't see the tank GameObjects in my subscene hierarchy so I can't check to verify but it seems like the shooting component is never disabled, or is not checked properly.

    Did I make a mistake somewhere, and is there a way to directly inspect the tank gameobjects while playing the scene? I'm using version 2022.2.0b13
     
  23. BUKRAR

    BUKRAR

    Joined:
    Jun 30, 2018
    Posts:
    1
    Hi , I have some question for sample
    In editor playing is fine , but Build window platform is not work 1.png 2.png

    Also tank sample have crash when I play in window platform,but in unity editor is work
    I use 2022.2.0.b16 entities 1.0
    I have no idea for this question , thx
     
  24. Foreverplane_

    Foreverplane_

    Joined:
    Nov 11, 2018
    Posts:
    11
    Hello! Can anyone explain about ISystem and SystemBase. I have read the docs. But I didn't understand.
    For example. ISystem is recommended because it works ОК with Burst. But foreach that main-threaded is used there.
    At the same time, a SystemBase with a burst is not OK, but there you can make a multi-threaded ForEach.ScaduleParallel "simple". (for the ISystem, in order to achieve such a simple look, you need to write an additional job)
    There is some simple version of multithreading in ISystem?
    Or is there not so much sense in ScaduleParallel in SystemBase?

    Thank you!
     
    DatCong likes this.
  25. DatCong

    DatCong

    Joined:
    Nov 5, 2020
    Posts:
    87
    Isystem can burst method like update, onCreate, ... That 's the different!
     
  26. Antypodish

    Antypodish

    Joined:
    Apr 29, 2014
    Posts:
    10,815
    @Foreverplane_

    Major difference is:

    ISystem is burst able, as previous poster.
    Plus you will be using idiomatic foreach on main thread.

    While SystemBase is not burstable.
    However you can use Entities.ForEach in parallel.

    Of course in both cases jobs can be burstable.
     
    Goularou and MadeFromPolygons like this.
  27. owlrazum

    owlrazum

    Joined:
    Jun 20, 2020
    Posts:
    5
    You can try to use Entity Hierarchy window in the editor, though I am not sure whether it will help you. Most likely you have made a mistake somewhere. Check the system scheduling the job too.
     
  28. owlrazum

    owlrazum

    Joined:
    Jun 20, 2020
    Posts:
    5
    I have a question regarding the TankSpawningSystem. It runs its tank creation code in the
    OnUpdate
    method. Is it possible or more appropriate to run it in the
    OnCreate
    method? If not, can
    OnStartRunning
    be utilized for it?

    I suspect that
    OnCreate
    is designed to be used for internal initialization of the system, with no structural changes. Is it true?
     
  29. Risho_Team17

    Risho_Team17

    Joined:
    Sep 30, 2020
    Posts:
    5


    The The Unity Job System video [2:40] states "Completing all scheduled jobs is required to avoid a resource leak"

    In the ECS tutorial, none of the scheduled jobs call the Complete() method. Are these not causing a resource leak? Or did I miss anything?

    (great tutorial btw!)
     
    Last edited: Dec 14, 2022
  30. Arnold_2013

    Arnold_2013

    Joined:
    Nov 24, 2013
    Posts:
    287
    In ECS the scheduling and completing of jobs is done for you. When a job needs to be completed for a different job to start ECS will make sure the dependent job is finished first. It automatically uses the data (components) that are used for all different jobs and works out which jobs are using (writing to) the same data and executes them in the right order. When data is only read it can be used in parallel by many jobs.
    There is a lot more detail in what scheduling you can influence in ECS, but I think this is the basic idea.
     
  31. PolarTron

    PolarTron

    Joined:
    Jun 21, 2013
    Posts:
    95
    I'm not a beginner to DOTS so this doesn't relate to me but I would like to show the guide to my beginner friends so I have some thoughts.

    I would love if the videos were split into two categories
    1. Minimum amount of information required to understand how to write high level code in DOTS.
    2. Extra information to understand how it all works under the hood and how to solve special cases with for example IJobChunk.

    The part where I feel most beginners would start to drift off is the part about Archetypes and Chunks and the Entity Metadata part in the video "Unity Entities package 1.0 - Entities and Components". Yes it's important to understand these concepts but the information is far too complex to chew through. People might drop off at that point.
     
    Voronoi and IsaacsUnity like this.
  32. Voronoi

    Voronoi

    Joined:
    Jul 2, 2012
    Posts:
    593
    I agree. I'm not a Unity beginner, but I really am struggling understanding how I would use DOTS, or even Jobs, Burst for that matter. It seems like a lot of overhead from my normal approach and would only really dive deep if I had a project that required the best possible performance.

    The first part of that tutorial was pretty clear, and as PolarTron guessed I started to drift off with talk about Archetypes and Chunks. I'm really just trying to understand the basics and not looking for a deep dive at the beginning.

    For me, I think I'll need a small game tutorial that incorporates DOTS as needed. I can't wrap my head around the need for sub-scenes and not seeing what is going on in the Editor. I used Unity to learn programming, and for me it was most helpful to have that combination of the Editor (things I can see) and then running the code. As things drift away from being in the Editor (Sriptable Objects, for example) it getss progressively harder for me to follow.
     
  33. EduardoLauer

    EduardoLauer

    Joined:
    Jun 10, 2013
    Posts:
    8
  34. Laicasaane

    Laicasaane

    Joined:
    Apr 15, 2015
    Posts:
    378
  35. IsaacsUnity

    IsaacsUnity

    Unity Technologies

    Joined:
    Mar 1, 2022
    Posts:
    94
    Thank you, we've updated the link!
     
    MagiJedi likes this.
  36. DreamersINC

    DreamersINC

    Joined:
    Mar 4, 2015
    Posts:
    133
    Did you find the source of your issue?
     
  37. Z_milk

    Z_milk

    Joined:
    Apr 21, 2020
    Posts:
    1
    +1
     
  38. NitinAltran

    NitinAltran

    Joined:
    Mar 9, 2021
    Posts:
    8
    Hi all I am making a network intensive game that requires making network calls very frequently I wanted to use burst for this purpose can some one tell will this be a right approach I am a bit new to ECS some initial guidance would be appreciated
     
  39. DatCong

    DatCong

    Joined:
    Nov 5, 2020
    Posts:
    87
    u could download the character controller package,it has a sample project about multiplayer.
     
  40. ITR

    ITR

    Joined:
    Apr 7, 2015
    Posts:
    21
    The HelloCube tutorial won't work if the cube is uniform, which might confuse new users trying to recreate the tutorial. I've opened a PullRequest that fixes the issue: https://github.com/Unity-Technologies/EntityComponentSystemSamples/pull/270
     
  41. hadynlander

    hadynlander

    Joined:
    Jan 24, 2014
    Posts:
    41
    You could probably do with a single onboarding tutorial which linearly walks new users through creating a simple ECS demo from scratch. The current onboarding via the github repo feels unnecessarily obtuse, relying on heavily hyperlinked documentation (sometimes to dead pages) and videos which only show the end result (even if annotated). The videos also tend to make statements about certain content being covered in other videos, but without any links or guidance on how to find that content it mostly feels like a tease.

    The internet is already packed with plenty of out of date information from earlier version of ECS, so I'm depending on official docs to get accurate guidance on getting started. It's not impossible to puzzle it all out from there, but I think a simpler, more linear walkthrough would go a long way towards making ECS more approachable.
     
  42. qisean

    qisean

    Joined:
    Sep 4, 2019
    Posts:
    1
    I found a reason, and I don't know why, but it worked for me. Write a script, write the OnGUI method, do not need to mount the script to the scene, and then, build, the entity is displayed.