PhysicsExamples2D, Unity's own 2D physics reference projects

What is in the repository and why there are several projects

This repository contains test projects, examples and a test package for Unity's 2D physics, spanning two API generations, and the split into separate projects is the point rather than an accident.

The Sandbox Project is described as interactive playground scenes that use the physics API directly. The Workshop Project is interactive workshop scenes that use the physics components. The NeonShooter Project is a neon-style 2D shooter demo built on the physics package, with experimental radiance cascades lighting. The Examples Package is unsupported experimental example components. OldPhysics2D is a set of examples that use the older Physics2D component API.

The distinction between Sandbox and Workshop is the one worth understanding. Sandbox exercises the API, the low-level interface where you create bodies, colliders and joints yourself. Workshop is built on the components, where you attach a Rigidbody2D and a Collider2D to a GameObject in the inspector and the engine wires them up. Both are useful, and they teach different things, because the component approach is a wrapper around the API and seeing the API underneath explains what the components are doing.

The OldPhysics2D directory is there for the same reason the NeonShooter project is: to show the previous generation, so you can see how a project written against the older API maps onto the new one.

To try your own physics, the README says to open the Custom, Empty example in either the Sandbox or the Workshop, and describes it as a blank canvas to build on. That is a sensible way to use the repository. Open the example, add your own setup, and compare the result against the other scenes in the same project.

The acknowledgements section credits Erin Catto, the creator of Box2D v3, on which significant portions of the Sandbox and Workshop projects are based. That is the single most useful technical fact in the README, because it tells you what the new 2D physics API actually is: Box2D, in a C# wrapper, rather than a proprietary engine.

Sandbox, Workshop and the two ways to use the API

The Sandbox project deserves a closer look, because the name undersells it.

It is described as interactive playground scenes that use the physics API directly, and the word interactive is the important part. These are scenes built to be poked at, not scripts to be read. A developer opens one, changes a body's restitution or a joint's frequency in the inspector, and watches the simulation respond. That is a much better way to build intuition about a physics engine than reading the documentation, and it is the reason the project exists alongside the manual rather than instead of it.

The distinction between Sandbox and Workshop is what makes the pair valuable rather than redundant. Sandbox exercises the API, the low-level interface where you create bodies, colliders and joints yourself, and the code in the scene is the part you read. Workshop is built on the components, where you attach a Rigidbody2D and a Collider2D to a GameObject in the inspector and the engine wires them up, so the scene configuration is the part you read. The component approach is a wrapper around the API, and seeing the API underneath explains what the components are doing.

The NeonShooter project shows the package under something resembling a real game, which is where the performance characteristics become visible, and the radiance cascades lighting is flagged as experimental, so it is a demonstration rather than a pattern to copy.

And to try your own physics, the README says to open the Custom, Empty example in either the Sandbox or the Workshop, and describes it as a blank canvas to build on. That is a sensible way to use the repository: open the example, add your own setup, and compare the result against the other scenes in the same project.

The acknowledgements credit Erin Catto, the creator of Box2D v3, on which significant portions of the Sandbox and Workshop projects are based. That is the single most useful technical fact in the README, because it tells you what the new 2D physics API actually is: Box2D, in a C# wrapper, rather than a proprietary engine.

The branch naming scheme and how to find your version

The branch convention is the part of this repository that will save you the most time, and the README explains it in detail.

Each branch represents a specific version of Unity. As features are added in a public release, those features should be represented in that branch and in future Unity version branches, so branch names such as 2022 and 6000.3 exist.

The three categories are clear. The master branch represents the Unity version currently in mid or late beta or final release, which means master is the branch to look at for the newest engine and is also the branch that will move. An unsupported/xxx branch represents versions in early releases that are not yet stable. And 6000.x style branches represent released Unity versions, kept as live branches while they are still supported.

So the practical rule is to find the branch matching your engine version, and only fall back to master if you are deliberately working against a beta.

The archive scheme is the other half. Older Unity version branches that are far out of support are not kept as live branches. They are archived as annotated tags named archive/<version>, with archive/2019 and archive/6000.1 given as examples. A tag preserves the exact final state of that version permanently while keeping the branch list focused on supported versions.

The reason to do this rather than keep the branches is worth understanding. A repository with a dozen live branches is a repository where nobody knows which one to open, and the branch list stops being a navigation aid. Moving the dead ones to tags keeps the list short and still preserves the content exactly, since an annotated tag is a permanent reference to a commit.

And the tags are usable. The README gives the command to turn one back into a working branch:

git branch 2019 archive/2019

That is the useful case for a team still on an old Unity version. Rather than checking out a tag and working in detached head state, you create a local branch from it, and you can commit to it normally.

Where the reference documentation lives and what to expect

The README links out to three things that are the actual documentation, and it is worth noting that the repository itself is examples rather than prose.

The first is the 2D Physics Core Manual in the Unity documentation, at a docs.unity3d.com path with a 6000.7 version in it. The second is the 2D Physics Package Documentation for the com.unity.2d.physics package, with a latest version reference. The third is a Dev Videos YouTube channel and a Twitter account and a Unity Discussions space, all under the same handle, melvmay.

The presence of a named individual behind all of those links tells you something about the project. This is the person who works on Unity's 2D physics, and the examples repository is where the work of documenting a physics system gets done. That is a different thing from a documentation site, and arguably more useful, because a scene you can open in the editor shows you the actual component values and the actual script rather than a screenshot of them.

The link structure also tells you the Unity version this repository currently tracks. A manual path containing 6000.7 and a branch named 6000.x together suggest the current generation of Unity releases is 6000.x, with the earlier ones numbered by year, which matches the archive examples given as 2019 and 6000.1.

What to expect from the examples themselves. The Sandbox project uses the physics API directly, so the code is the interesting part. The Workshop project uses the components, so the inspector configuration is the interesting part, and the same behaviour is achieved with a different amount of code. The NeonShooter project is a demo that shows the package under something resembling a real game, which is where the performance characteristics become visible, and the radiance cascades lighting is flagged as experimental, so it is not a pattern to copy.

One thing the README does not do is explain what the test package is for. The Examples Package is described as unsupported experimental example components, and a package whose components are unsupported is worth reading as a source of ideas rather than as something to depend on. If you adopt a component from there, you are adopting something the Unity team has explicitly marked as unsupported, and you should check what replaced it.

For a team upgrading an existing 2D project, the OldPhysics2D directory is the most directly useful part, because it shows the same scenes expressed in the previous API and makes the migration differences visible rather than theoretical.

Editorial conclusion

Adopt these projects as a reference when you are working with Unity's 2D physics, because they show the intended usage of both the new API and the older component API in scenes you can open and step through. Skip it if you are on a Unity version whose branch has been archived, since those exist only as annotated tags. Verify first by opening the Custom, Empty example in the Sandbox project and running it in the editor, since a blank canvas is the intended starting point for trying your own setup.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Unity-Technologies/PhysicsExamples2D on GitHub