Making Sandspiel | max-bittker

Sandspiel is a falling sand sport I inbuilt late 2018. I actually loved scripting this sport, and needed to place into writing a few of my objectives, design selections, and learnings from that course of. In case you’re studying this however haven’t performed sandspiel, you need to most likely go try it!

I really like falling sand video games.

If Sandspiel is the primary “falling sand sport” you’ve performed, it’s essential to know that it matches right into a style of video games, that are developed independently and often distributed as free webgames within the type of flash or java applets. In every sport, you’re given a pallette of digital solids, liquids, and gasses, and it’s as much as you to color them onto the display to find how they work together.

I feel that I really like these video games a lot as a result of their mode of play is artistic in a means that prompts many elements of your creativeness. Enjoying with the weather means asking questions, constructing experiments, and inventing tales and video games of your personal.

“What does fungus do?”

“Let’s make a cool volcanic island!”

“Does something destroy lava?”

“What occurs if I do this?”

In sand video games, identical to in different mobile automata (such because the Recreation of Life), the conduct of any single aspect may be very easy. The interactions between the weather and throughout the area is the place the attention-grabbing complexity of the simulation unfolds. The result’s a system with stunning depth and selection to discover.

It’s additionally essential that this method is partaking not only for its precise depth, but additionally due to the methods your creativeness sees actuality mirrored in it. Predicting how a situation will play out primarily based in your bodily instinct is a type of play, as is projecting your creativeness over what you see represented on display. Very like taking part in with dolls or different simplistic mannequin, the pixels flowing round on the display are stand ins for the story you inform your self about them.

“Low-fidelity artwork can be appealingly open to interpretation. If a personality is simply eight pixels tall, a big a part of what we see is inside our personal creativeness.” – Loren Schmidt

Microcommunity

Everybody likes to opine on their forgotten, bizarre corners of the web, and mine is the add gallery of dan-ball.jp’s Powder Recreation round 2007-2013. There was a stupendous micro-culture of individuals making video games, toys, demos, propaganda, and artwork.

Powder Recreation’s add galleries had been a particular place — the accessible venue to construct one thing and share it led to folks inspiring one another, riffing, and pushing the sport in unbelievable instructions! Sand video games captured my free time and creativeness all through my childhood largely due to this bizarre group.

It’s additionally essential that this method was constructed proper into the sport — each participant had a fast viewers for his or her creation, in distinction to a tradition constructed round a couple of well-known youtubers or streamers, and even that peculiar type of self-selecting group you discover on fanatic boards. There was all kinds in complexity and motivations amongst posters. All this with no remark part!

Three archetypes of add I bear in mind fondly:

Video games for the participant, usually with empty guarantees of some reward for voting.

Grotesque “Don’t Smoke” instructional demonstrations. (I feel these had been straight fueled by youngsters coming residence after D.A.R.E. packages in school)

Cool volcanos. (a real basic)

Lovely pixel-art structure to destroy.

The added dimension of an viewers brings a lot depth to taking part in round with sand. I needed to facilitate this in sandspiel with the add system.

Constructing Sandspiel

The very first thing you need to know is that Sandspiel is definitely my third or fourth try at constructing an interactive falling sand simulation.

“HTML5”

The primary correct try was pure javascript in 2015. (You can try it out here!)

It’s… a falling sand sport! You possibly can set issues on fireplace, draw fountains, and there’s even a fluid simulation that permits particles to drift round within the wind. I feel my favourite issues about this sport was making pixel artwork with the rainbow “Mud” aspect, and the best way that “Grime” absorbs and diffuses water to change into mud.

On the detrimental facet, decision is simply 100×100 (Sandspiel has 9x extra pixels), doesn’t work on a cellphone, the interface is complicated and keyboard primarily based, and the aspect logic is fairly janky.

It’s additionally rendered with canvas APIs, and the code shouldn’t be organized in any intentional means. Loads of dynamic typing, gnarly swap statements, and international variables. All of this made implementing and debugging every successive aspect’s logic more and more troublesome— to the purpose that it resulted in bugs that I domesticated and saved within the sport, such because the aspect “Glitch” which behaves in a different way relying on what aspect you might have chosen.

I used to be actually pleased with this sport and had a good time constructing it, nevertheless it adopted the acquainted arc of a system collapsing underneath its personal weight as progress grew to become tougher and motivation waned. The final commit message was type of basic, and I by no means did comply with up on that “impending refactor”.

LÖVEly

The second approach was with Lua in 2018, and my work right here turned out to be the direct prototype for Sandspiel.

A number of issues are briefly value saying on this expertise:
First I have to gush that lua is tremendous quick due to LuaJIT, and the LÖVE framework is beautiful instrument for constructing video games.
Shaders, enter dealing with, replace and render loops — every little thing clicked collectively due to LÖVE and made life straightforward – I may get issues operating rapidly with minimal yak shaving and boilerplate.

Coming from the browser, a instrument into which I’ve personally sunk many tons of of hours studying APIs, edge circumstances, and efficiency traits, it was a giant shock to see how efficient a minimal programming setting for constructing video games might be. A lot complexity that we put up with is because of legacy and sunk prices!

Coming into this second try and construct a sand sport, I had 3 years of expertise past what I had when constructing the pure javascript model. I additionally had an essential new objective – not solely did I would like the sport to be enjoyable to play, however I additionally needed parts to be enjoyable to write.

I approached the undertaking with a give attention to the ergonomics of defining parts with code as a result of I used to be imagining a brand new sort of sand sport with a totally sandboxed programming interface that might permit folks to not solely paint and share their compositions, but additionally to code their very own new parts and share these too!

My hope was {that a} group of individuals collaborating to construct a plethora of bizarre parts would discover actually attention-grabbing interactions that hadn’t been coated in different sand video games.

Nevertheless, this was a giant objective, and step one of the method was nonetheless constructing out a sport engine and preliminary set of parts alone. Whereas constructing these, I used to be considering rigorously in regards to the wants of the long run aspect authors. Viewing the sport engine as a public API meant designing it to maneuver as a lot complexity as doable contained in the engine and away from being the duty of the person parts.

operate updateGas(particle, getNeighbor, setNeighbor)
    native d = {x = math.random(-1, 1), y = math.random(-1, 1)} 
    if (getNeighbor(d) == species.empty) then 
        setNeighbor({x = 0, y = 0}, species.empty) 
        setNeighbor(d, particle) 
    finish
finish

This meant defining a format that parts had been expressed in — I settled on a single replace methodology which defines the conduct of a single particle for a single replace tick. The code inside the strategy can work together with the system solely by way of particular strategies which offer protected studying and writing to their neighbors.

This API abstracts away considerations reminiscent of:

• The particle needing to know its absolute place (setNeighbor and getNeighbor deal in relative offsets),
• Interactions with the perimeters of the grid (the entire edge situation logic is within the engine),
• Implementing a small native learn/write neighborhood for the particles (no “motion at a distance”).

That work relieved the person parts from needing to tackle these considerations into their very own logic, and made the system extra constant and simpler to experiment with as I carried out my forged of parts.

Specializing in making the definition of a brand new aspect easy and self-contained actually paid off, despite the fact that I finally ended up being the one individual consuming these APIs. The system being extra enjoyable to iterate on was rewarding sufficient to justify the additional care put into the structure early on.

I used to be enthusiastic about this method and it was working nicely, however needed to construct the sport in a means that I may attain customers. Regardless of every little thing good I needed to say about LÖVE, the net is just too highly effective of a platform to go up, and it’s definitely worth the quirks and warts.

I made a decision to place down the lua implementation and swap to Rust, however I used to be in a position to straight translate many classes and patterns over. Having a good suggestion of what my data-structures could be and what forms of APIs could be outlined between parts made writing the Rust model a lot smoother.

Implementing one concept a number of occasions was an enormous power in my means to construction my codebase, forsee pitfalls, and make extra considerate and intentional tradeoffs. I might strongly advocate this expertise to anybody – When you have a undertaking that you simply’ve tried up to now however both didn’t end or made compromises on because of your technical expertise or endurance, taking one other crack at it might a fantastic alternative to sweat the main points and see new approaches.

Structure:

Sandspiel.membership could be described as 4 major parts

• the particle simulation code, written in Rust
• a fluid simulation, written in JS & GLSL
• person interface written in React & JS
• a CRUD backend written with TypeScript and Firebase Postgres

The principle simulation, controlling the motion and interactions of the entire parts, takes place in Rust in a category referred to as Universe. That is the category holds the sport state and exports a set of strategies to be referred to as by the Javascript utility, which do issues like course of a body of the simulation, paint some pixels, or return a pointer to the particle state buffer.

Which means I don’t attempt to deal with an occasion loop, do rendering, or work together with the browser from contained in the Rust code – all of that might be completely doable, however I’m very proud of this division of labor between the JS and Rust. All the pieces low stage or CPU intensive occurs inside the Rust-generated Net Meeting code, whereas the entire the glue associated to human interface, WebGL calls, and browser APIs takes place within the Javascript.

Information format

The primary most notable facet of Sandspiel’s structure is the compact information format I used for the sport state. By setting some constraints on the system, I used to be in a position to profit from a uniform format that carried out and serialized nicely. This got here in helpful a number of occasions!

The state for a single particle is represented as a 32 bit struct.

#[repr(C)]
pub struct Cell {
    species: Species,
    ra: u8,
    rb: u8,
    clock: u8,
}

The primary discipline, species, is a customized enum sort which represents the kinds of particles as numbers:

#[wasm_bindgen]
#[repr(u8)]
pub enum Species {
    Empty = 0,
    Wall = 1,
    Sand = 2,
    Water = 3,
    ...
    Seed = 19,
}

ra and rb are two 8 bit “registers” for storing further some cell state past species, reminiscent of what coloration a given flower petal is, or how sizzling an ember of fireplace is. They’re utilized in alternative ways by completely different aspect species, and a few species don’t use them in any respect (as an illustration, a Wall particle has no further state to trace). The 2 state registers solely differ in that ra is initialized to a random worth, and rb is initialized to 0. ra can be utilized in rendering to find out how gentle the pixel needs to be, which is the place the slight visible grain impact comes from.

clock is simply used to stop a single particle from being simulated a number of occasions in a single tick if it strikes in the identical path because the replace scans. As a result of we execute cell replace features one after the other from left to proper and prime to backside, if a particle one thing is transferring down, it’s going to maintain bumping itself forward of the “scan line” and will transfer many areas in a single body. Clock is supposed to maintain observe of what parts have been simulated already – this might have been completed single bit that’s flipped forwards and backwards nevertheless it’s essential that my Cell sort is represented by a complete of precisely 32 bits, and I didn’t have any use for the opposite 7 bits!

Nowhere on this cell state struct is an idea of location. It’s because, versus a particle simulation the place we preserve an inventory of entities and their positions, right here we retailer all particles in a dense 2D array, and straight encode the place of a cell as its location in that grid.

Replace Operate

A very powerful items of code within the sport are the set of features, one for every sort of aspect, that outline how particles of that sort work together with their neighbors every body. Theoretically, you could possibly delete these features (which stay in species.rs ) and write a brand new set that remodel the sport right into a mobile automata simulator for another system, such an ant farm, a petri dish, a city-scape, a paint canvas, an aquarium, or an summary fractal playground.

Right here’s an instance of how one in all our parts is outlined:

pub fn update_sand(cell: Cell, mut api: SandApi) {
    let dx = rand_dir(); 
    let neighbor = api.get(0, 1); 

    if neighbor.species == Species::Empty { 
      api.set(0, 0, EMPTY_CELL); 
      api.set(0, 1, cell); 
    } else if api.get(dx, 1).species == Species::Empty { 
      api.set(0, 0, EMPTY_CELL); 
      api.set(dx, 1, cell);  
    }
}

SandApi is a struct offered to the operate which holds the situation of the particle with out straight exposing their values. It exposes some essential features, like get and set, which settle for relative coordinates and allow you to learn and write to your neighboring cells. As an example, api.get(0, 1).species tells you the species of the particle beneath you, and calling

api.set(0, 0,
   Cell {
      species: Species::Fireplace,
      ra: 150,
    }
  );

will write a Fireplace particle to your present location (erasing your self within the course of).

Designing and tuning these replace features was a variety of enjoyable, and I used to be in a position to take a look at out a variety of concepts and play with completely different interactions. I didn’t make use of syntax macros or something as fancy as that, however the expertise was loads like that of constructing a system by first constructing a “Area Particular Language” which encodes the shared behaviors and invariants of the system, after which scripting its inhabitants in that simplified DSL.

One other factor to notice right here is that these replace features, which maintain a lot of the gameplay logic, are run 1000’s of time per body! Which means they’re concurrently essential to the texture of the sport, and are among the hottest strains of code within the undertaking. Rust’s dedication to enabling expressive, excessive stage code with out invisible efficiency cliffs actually allowed me to put in writing the logic how I needed to put in writing it, with out by accident inflicting a bunch of gradual heap allocation or writing code {that a} JIT will capriciously resolve to not optimize. It’s most likely doable that there are folks on the market who may rigorously craft some high-performance javascript that might be aggressive with my Rust code, however I used to be in a position to principally “simply code” and never fear an excessive amount of about efficiency.

Zero value abstractions!

Final attention-grabbing anecdote right here is that I unwittingly wrote a lot of the sport with my rustc optimization technique on “z”, which suggests the compiler will optimize for binary dimension. As soon as the undertaking was nearly completed, I noticed this and switched it to “o3” which does issues like inlining and gave me a giant efficiency enhance, the place I had been being frugal! That was a pleasant shock, it carried out higher and the WASM output solely elevated in dimension from 66Kb to 84Kb.
A giant mistake I made was to right away take this further efficiency funds and “spend it” to extend my canvas dimension from 250×250 to 300×300, as a result of now I may nonetheless get 60 fps on the 300×300 canvas.
This was a blunder as a result of there are a ton of units which might’t run sandspiel at 60fps, and I ought to have held onto this spare efficiency headroom in order that extra units may run the simulation at full pace.

Rendering

I discussed that the simulation takes place in Net Meeting, and that the Javascript manages the WebGL rendering (it’s totally possible to call WebGL APIs directly from web assembly, however I didn’t need to compound my WebGL inexperience with my Rust inexperience).

Rendering is principally as straightforward as studying every cell of our gamestate grid, and portray a corresponding pixel with a coloration in accordance with its species and ra values.

We simply have to guarantee that our fragment shader (the code which runs on the GPU and decides what coloration the pixels needs to be) has entry to the sport state, which is saved within the Net Meeting heap.

In an effort to transfer the sport state from Net Meeting to WebGL, we assemble a Javascript typed array view over the sport state array which lives in Net Meeting reminiscence, and go that view to our fragment shader (GPU code) as a texture.

const cellsData = new Uint8Array(
  reminiscence.buffer,
  universe.cells(), <- 
  width * peak * 4
);

gl.bindTexture(gl.TEXTURE_2D, cellTexture);
gl.texImage2D(
  gl.TEXTURE_2D, 0, gl.RGBA,
  width, peak, 0, gl.RGBA, gl.UNSIGNED_BYTE,
  cellsData
);

As a result of our sport state information is organized in such a means that it occurs to be a legitimate picture texture, we will ship the entire grid over to the GPU with minimal copying and allocation! This was a giant deal for making Sandspiel’s rendering performant- the rendering code blocks the CPU for lower than 1 millisecond, essential for assembly the strict 16ms funds wanted to realize 60FPS.

That is additionally one of many causes it was so essential that our Cell state was saved as an array of 4 byte chunks. WebGL has a variety of restrictions on the codecs of information that can be utilized in textures, however RGBA textures the place every pixel is 4 unsigned bytes are nicely supported.

Fluid Dynamics

Sandspiel’s fluid simulation often actually stands out to individuals who play with it, which makes me really feel a bit of bit responsible, as a result of it’s largely ripped from Pavel Dobryakov’s WebGL Navier-Stokes implementation. I’m extraordinarily grateful to have had such a high quality implementation to study from— adapting and increasing this code was essentially the most personally difficult technical hurdle I confronted constructing the sport.

Adapting the code was troublesome as a result of, with the intention to have interactions between the wind (simulated on the GPU) and the particles (simulated on the CPU), I wanted to go information from Net Meeting to WebGL (in the identical style as I discussed for the rendering), and from WebGL again into to Net Meeting (this bit was trickier, as WebGL can by choosy about which buffers are readable, and when you possibly can learn from them).

I additionally wanted to do that in a means that used solely the subset of WebGL options supported on most telephones – WebGl is a fairly large spec, and for {hardware} and driver causes, not all of it’s out there on all units.

This course of was made worse by the truth that my solely cellphone on which to check code runs iOS, and Apple solely permits you to hook up with the cell safari developer instruments from a Mac (which I don’t have). So I used to be debugging many of those WebGL device-specific limitations with out a lot as a console. Irritating!

Person Interface

Sandspiel’s interface is definitely a lot less complicated than most falling sand video games. I made an intentional effort to maintain the UI gentle and enjoyable on a contact display, by avoiding interactions that require a number of faucets to finish. Some examples of this are that not one of the instruments require biking via completely different settings or drop-down menus, and I dropped the system of two-stage choice that different video games use to implement parts like clone and firework.

See Also

“They don’t care”: Contained in the triumphs and failures of accessible gaming {hardware}

I additionally put care into the road drawing itself – there’s some fiddly edge circumstances associated to dealing with faucets, drags, scrolling, and different interplay occasions on the canvas. That is the type of tuning that needs to be invisible if it’s working, however I bumped into a variety of interplay situations whereas testing the sport, and tried to sand down the tough edges.

As a part of this work, I disabled pinch-to-zoom – it will be an attention-grabbing problem to attempt to match that again into the area of supported interactions.

Facilitating and disambiguating a number of gestures in a single enviornment is a fancy and interesting nook of algorithms and human pc interplay, and I’ve new respect for the usually invisible work that goes into constructing wealthy contact display experiences.

UI Code

I threw the interface collectively principally in React. When you have one takeaway about Net Meeting from this undertaking, I would like it to be that WASM shouldn’t be an all or nothing endeavor! Being able to place low-level and performance-critical logic into Rust and nonetheless deal with all of the browser API stuff, glue code, and UI in Javascript was essential to this undertaking coming collectively rapidly and having a pleasant interface.

Leveraging the npm ecosystem for instruments like React, Regl, and GLSLify, in addition to exercising Javascript’s flexibility to toss information wherever I wanted it with out a lot planning or refactoring enabled me patch issues collectively rapidly and loosely.

Nothing I wrote in JS would have been unattainable to perform in Rust, nevertheless it wouldn’t have come collectively as simply and I wouldn’t have been in a position to take a look at as many concepts alongside the best way.

Sharing & Persistence

To completely seize the artistic micro-community of different falling sand video games, I needed there to be performance for importing creations, and shopping others’ works. I made a decision to attempt utilizing Firebase to deal with my backend wants, and I feel that labored out fairly nicely!
One design resolution that turned out to be essential was that I needed to keep away from coping with accounts and authorization. I discover that stuff annoying for the person and boring to implement so I went to some lengths to do with out it.

The best way that I dealt with information safety with out auth was placing all information writing inside api endpoints, and utilizing these to constrain what the consumer may do. (principally, GET, INSERT and voting solely, no modifying or deleting of different posts). My workaround for voting deduplication was to make use of IP addresses, which is feasible to control, however I don’t actually care sufficient to attempt to battle it.

I run these API endpoints as a cloud operate, cloud features appear low cost and nice.

A cool factor right here in regards to the storage performance is that I serialize the sport state as a PNG file, which is lossless and extremely compressible. Plus, browsers have environment friendly PNG encoders and decoders inbuilt, in order that’s extra code I don’t have to import and ship with my bundle.
Right here’s what the information appears like as a PNG: (bear in mind, in every RGB pixel, “pink” is species, “inexperienced” is ra, and blue is rb)

The fundamental structure of my backend is one thing like this:

There have been occasions whereas debugging once I was actually simply wished I used to be writing a http server backed by a redis occasion and a listing filled with recordsdata, with nothing hidden behind proprietary providers and configuration languages. However I don’t need to be on the hook for availability, persistance, and server administration – particularly when the other things operating on my VPS are already fragile, stateful, and advert hoc. Firebase was more durable to debug and run adhoc scripts towards, however I don’t have to consider it now that the service is deployed, and it’s dependable and low cost sufficient.

Operating the sport for a couple of months began to change into costly as visitors ramped up, 99% dominated by Firestore reads. (I feel the structure I had of itemizing out giant sections of paperwork with out caching or pagination wasn’t nicely suited to Firestore.)

I didn’t need to proceed paying $50 a month for Firestore, and I additionally needed to implement extra attention-grabbing question capabilities, together with full-text search.

This led me emigrate my ~60k data off of Firestore and right into a Postgres occasion, which I’m actually glad to have executed. Working Postgres has been about 10% of the worth, considerably decrease latency, and permits me to run complicated queries to energy new options just like the search field.

Group

A couple thousand folks play with sandspiel day-after-day now! The add boards get spammed with all kinds of magnificence and nonsense, and it warms my coronary heart to see folks taking part in, interacting and (principally) having enjoyable. The playerbase skews fairly younger, and uploads are full of memes, youngsters selling their youtube accounts, and many others and many others. For essentially the most half, it will get used as a paint program, and the precise simulation features are an afterthought!

In case you load one creation, this irreverent homage to the Notre Dame cathedral could be my favourite:
(Ensure to press ▷ as soon as it’s loaded)

Folks have uploaded greater than 70,000 creations, starting from subtle rube goldberg reactions, coloring ebook “full the drawing” prompts, impressionist paintings, crude kinetic graffiti, and every little thing in between.

One add that shocked me was when somebody manipulated the information buffer straight, to add out-of-range species information. This resulted in a pink aspect with no deliberately outlined conduct, just like the ”MissingNo.” of sandspiel. It completely made my day once I realized what had occurred, as this was not one thing I believed was doable! I like to call it “belp”.

There’s a wholesome remix tradition of individuals making new takes on fashionable templates. Two favorites are doonaloona, the lithuanian pet queen of sandspiel

and these photos of reggie that somebody was in a position to someway hack into the sport in several parts.

Thanks a lot for studying this lengthy publish!

The Rust Wasm Book is a nice succinct useful resource that covers all features of writing a hybrid JS & Rust utility. I had fundamental rust data earlier than beginning Sandspiel, however no data of net meeting, and was in a position to comply with this ebook to bootstrap the sport. Loads of code from the ebook really ended up in my sport, since their instance was mobile automata associated.

The Book of Shaders I didn’t particularly reference TBoS throughout this undertaking, however I take any alternative I can get to advocate it to anybody considering studying graphics programming. I want this ebook was part of highschool math curriculums.

WebGL Fundamentals & WebGL2 Fundamentals Actually strong & full explanations of WebGL fundamentals, put into context of widespread duties and patterns. Discovering these two issues collectively is uncommon!

Fast Fluid Dynamics Simulation on the GPU is a chapter from the ebook GPU Gems, which particulars the maths and mechanics that go into a stupendous and buttery Navier Stokes fluid simulation. It’s actually attention-grabbing how bodily ideas like stress, advection, and diffusion, all expressed as math operations on grids of floats, could be composed right into a convincing simulation.

Additionally, due to Chris Crawford, Nikhilesh Sigatapu, Thais Correia, Pavel Dobryakov, the Rust WebAssembly working group, and ha55ii for inspiration, data, code, and suggestions!

sandspiel source code

@sandspiel_feed twitter feed of uploads