Simulo is a web-based TypeScript 2D physics sandbox and game engine with scripting support and soon multiplayer. It uses Box2D for physics and currently Canvas for rendering, though WebGL support is planned.

• Developer Guide
  • Introduction
  • Getting Started
    • 1. Cloning the Repository
    • 2. Installing Dependencies
    • 3. Building and Running
  • Modules
    • Server-side Physics Diagram
    • Client-side Physics Multiplayer Diagram
    • Client-side Physics Singleplayer Diagram
  • File Structure
  • FAQ
    • Why is the client and server in the same repo?
  • Contributing
  • License

If you're interested in contributing to Simulo or just curious about how it works, you've come to the right place! This guide will explain everything, like how to run Simulo, the architecture of Simulo, and much more.

Firstly, when we say "server" in this guide, we mean the host of the Simulo room. When we are talking about the web server, we will explicitly say "web server", so keep that in mind and remember that the host often runs on the client.

Simulo is a TypeScript project which is designed to let both the web server and the client host. As multiplayer support is currently broken, hosting on the web server has not been tested in a while, but even if it doesn't currently work, it should be easy to fix.

The Simulo web server uses Node.js Express, and the client uses a custom game engine (named the Simulo engine or just Simulo) which uses Box2D for physics and Canvas for rendering. No framework is used on the UI to keep things simple, as it's just one page. Soon, a basic Simulo website will be set up, and since it'll just be 2-3 pages, it will most likely not use a framework either, though this is subject to change.

If you don't have Node.js, NPM and Git installed, install them now. You can find them at https://nodejs.org/en/ and https://git-scm.com/downloads respectively.

Clone the repository with this command:

git clone https://github.com/Carroted/Simulo.git

Or, if you have GitHub SSH set up:

git clone git@github.com:Carroted/Simulo

Next, you should install the dependencies. To do this, run this command:

npm i

Finally, you can build and run Simulo. To do this, run this command:

npm run build && npm start

If you want to start it later without rebuilding, you can just run this command:

npm start

The opposite is true for building without starting.

Building will take between 10 and 40 seconds, so try not to get frustrated if it takes a while.

In Simulo, we have 3 kinds of modules. These are client modules, server modules and shared modules.

Client modules are only run on the client, server modules are only run on the server, and shared modules are run on both the client and the server. This is useful for things like physics, which need to be run on both the client and the server. (remember again, by server we mean host, not web server)

Here's a handy table of most modules:

Here's a handy diagram to help you understand how the server-side physics works:

Here we have 3 modules running on the server:

• SimuloPhysicsServer - Wrapper of Box2D (liquidfun-wasm) which makes it way easier to use
• SimuloServerController - Hosts the room and manages the physics, tools and more
• SimuloNetworkServer - Currently broken, but hosts WebRTC and WebSocket

We also have 3 modules running on the client:

• SimuloNetworkClient - Currently broken, but connects to the server via WebRTC and WebSocket
• SimuloClientController - Manages UI, tools, NetworkClient and Viewer
• SimuloViewer - Renders SimuloShape data and sets up panning and zooming (will be moved to SimuloClientController soon)

Here we have a peer as the host, with another peer connected to it:

You'll notice it's almost the same, except for the 3 new nodes attached to SimuloServerController:

• SimuloLocalClient - Loopback which connects directly to SimuloServerController and is used for the host
• SimuloViewer - Renders SimuloShape data and sets up panning and zooming (will be moved to SimuloClientController soon)
• SimuloClientController - Manages UI, tools, NetworkClient and Viewer

Same but singleplayer:

We just cut off SimuloNetworkServer and everything connected to it.

Here's a handy diagram of the file structure:

I forgoy 💀

Since a lot of modules are shared between the client and server, it's easier to have them in the same repo.

To get started, check out the issues at https://github.com/Carroted/Simulo/issues/. If you want to contribute, fork the repo and make a pull request. If you want to make a big change, make an issue first so we can discuss it.

GNU GPLv3