Warning

This project has been archived as we are working on a rewrite of it in Rust! See simulo_bevy.

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.

Table of Contents

• 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

Developer Guide

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.

Introduction

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.

Getting Started

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.

1. Cloning the Repository

Clone the repository with this command:

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

Or, if you have GitHub SSH set up:

git clone [email protected]:Carroted/Simulo

2. Installing Dependencies

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

npm i

3. Building and Running

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.

Modules

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:

Name	Description
SimuloPhysicsServer	Wrapper of Box2D (liquidfun-wasm) which makes it way easier to use
SimuloNetworkServer	WebRTC and WebSocket server
SimuloNetworkClient	Receives data from NetworkServer, which is sometimes the client (loopback)
SimuloViewer	Displays the world, plays sounds and captures input from mouse, controller and keyboard
SimuloClientController	Controls the client, gets input from Viewer and sends it to NetworkClient
SimuloServerController	Hosts the room and manages the physics, tools and more
SimuloLocalClient	Works identically to NetworkClient, but instead of getting data from network, it gets it directly from ServerController to avoid host sending data through network back to itself

Server-side Physics Diagram

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)

Client-side Physics Multiplayer Diagram

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

Client-side Physics Singleplayer Diagram

Same but singleplayer:

We just cut off SimuloNetworkServer and everything connected to it.

File Structure

Here's a handy diagram of the file structure:

I forgoy 💀

FAQ

Why is the client and server in the same repo?

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

Contributing

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.

License

GNU GPLv3