Nu API Revamp + Coroutines!

[bryanedds]

This release features a very large Nu API revamp that makes interfacing with the engine and writing game code significantly more ergonomic and streamlined!

Previously, the World value had to be manually threaded through every API call that caused the world to change in any way. Because of how pervasive state transformation are in games - even immutable transformations! - this meant you often ended up having to write code in a much more verbose style. This release changes all that, making the World type just a handle to the underlying immutable new WorldState value. This is a very enabling thing, and not just for code ergonomics! Because of that change, we are now enabled to provide you a Unity-style coroutines programming model as well - https://github.com/bryanedds/Nu/wiki/Frame%E2%80%90Based-Behavior-with-Coroutines

Additionally, writing ImSim code becomes so much easier and to the point. In stead of having to user ternary if expressions and folds everywhere, ImSim code becomes composed of imperative style ifs and for loops - almost like you're writing Python scripting code but with the power of declarative and functional programming!

Here's some ImSim code from the Breakout ImSim project before this API change -

        // declare bricks
        let world =
            Seq.fold (fun world (brickName, brick) ->
                World.doBlock2d brickName
                    [Entity.Position .= brick.Position
                     Entity.Size .= brick.Size
                     Entity.Sensor .= true
                     Entity.Color @= brick.Color
                     Entity.StaticImage .= Assets.Default.Brick] world |> __c)
                world (gameplay.GetBricks world).Pairs

        // declare score
        let world = World.doText "Score" [Entity.Position .= v3 248.0f 136.0f 0.0f; Entity.Text @= "Score: " + string (gameplay.GetScore world)] world

        // declare lives
        let world = World.doText "Lives" [Entity.Position .= v3 -240.0f 0.0f 0.0f; Entity.Text .= "Lives"] world
        let world =
            List.fold (fun world i ->
                World.doStaticSprite ("Life+" + string i)
                    [Entity.Position .= v3 -240.0f (single (inc i) * -16.0f) 0.0f
                     Entity.Size .= v3 32.0f 8.0f 0.0f
                     Entity.StaticImage .= Assets.Default.Paddle] world)
                world [0 .. dec (gameplay.GetLives world)]

        // declare message
        let messageText = if gameplay.GetLives world <= 0 then "Game over!" elif (gameplay.GetBricks world).Count = 0 then "You win!" else ""
        let world = World.doText "Message" [Entity.Text @= messageText] world

        // declare quit button
        let (clicked, world) = World.doButton "Quit" [Entity.Position .= v3 232.0f -144.0f 0.0f; Entity.Text .= "Quit"] world
        let world = if clicked then gameplay.SetGameplayState Quit world else world

Certainly more succinct than imperative or OO code, but here it is after -

        // declare bricks
        for (brickName, brick) in (screen.GetBricks world).Pairs do
            World.doBlock2d brickName
                [Entity.Position .= brick.Position
                 Entity.Size .= brick.Size
                 Entity.Sensor .= true
                 Entity.Color @= brick.Color
                 Entity.StaticImage .= Assets.Default.Brick] world |> ignore

        // declare score
        let scoreText = "Score: " + string (screen.GetScore world)
        World.doText "Score" [Entity.Position .= v3 248.0f 136.0f 0.0f; Entity.Text @= scoreText] world

        // declare lives
        World.doText "Lives" [Entity.Position .= v3 -240.0f 0.0f 0.0f; Entity.Text .= "Lives"] world
        for i in 0 .. dec (screen.GetLives world) do
            World.doStaticSprite ("Life+" + string i)
                [Entity.Position .= v3 -240.0f (single (inc i) * -16.0f) 0.0f
                 Entity.Size .= v3 32.0f 8.0f 0.0f
                 Entity.StaticImage .= Assets.Default.Paddle] world

        // declare message
        let messageText = if screen.GetLives world <= 0 then "Game over!" elif (screen.GetBricks world).Count = 0 then "You win!" else ""
        World.doText "Message" [Entity.Text @= messageText] world

        // declare quit button
        if World.doButton "Quit" [Entity.Position .= v3 232.0f -144.0f 0.0f; Entity.Text .= "Quit"] world then
            screen.SetGameplayState Quit world

No longer to new users have to spend time learning the ropes of writing interwrited folds and babysitting the world value for reasons that are necessarily initially apparent. New users can now get up to speed on Nu game development both quickly and have more fun over the game dev process due to this significant reduction in development friction!

More and more benefits are being hatched based on the new API as well, which we'll surface as we discover and prove them out!

Also, special thanks @Happypig375 for the part of the discussion that led me to pull the trigger on these API-wide changes as well as helping to prototype and shape the new coroutines feature!

New Contributors

• @Happypig375 made their first contribution in Use implicit yields for Coroutine, elide unit argument for sleep and cancel #1051

Full Changelog: v18.17.0...v19.0.0

---

This discussion was created from the release Nu API Revamp + Coroutines!.