Guide

How to build a space sim and submit it to the ORBIT galaxy.

What counts as a sim?

To be defined as a sim, your project needs to be:

• Interactive - users need to be able to change starting conditions or affect the sim while it runs. This could be for example, clicking to add planets, dragging to aim a rocket, tweaking a slider to change gravity.
• Visual - something needs to move on screen. It can be 2D, 3D, pixel art, realistic as long as there's a visual representation of the simulation.
• Space-themed - planets, stars, rockets, black holes, galaxies, orbits, asteroids, nebulae. Your sim needs to be space-related in some way.
• Runs in the browser - no downloads! A visitor should be able to open your URL and check out what you've built straight away.

Your sim doesn't need to be super complicated or impressive.

Recommended libraries

• p5.js - a beginner friendly js library.
• Three.js - for 3D. Has a steep learning curve, but can produce really beautiful sims.

These are just some suggestions if you are a beginner. You can use whatever you want to make your sim!

Starter tutorial

Guides you through how to make a simple sim that gets a planet to orbit your cursor. This takes about an hour.

1. Set up your files

Create a folder with two files:

index.html 
 script.js

In index.html:

This just loads p5.js, (the drawing library) and your js file.

2. Set up the canvas

In sketch.js, start with the variables and setup:

• x, y - the planet's current coordinates. These will update throughout the sim.
• vx, vy - the planet's current velocity in each direction. We'll give it a small sideways push to start.
• createCanvas - makes a canvas the size of the window that our js can draw directly onto for our sim.

3. Add gravity

Now the draw() function, which will run once per frame:

• dx, dy - the horizontal and vertical distance from the planet to your mouse.
• dist - the actual direct distance between them, worked out using the pythagorean theorem. We clamp it to at least 20 so things don't explode when the planet gets too close.
• force - The strength of the cursor's gravity is calculated using the / (dist * dist) is the inverse-square law - gravity gets weaker the further away you are, like in real life.
• We add the force to the velocity, pulling the planet towards the mouse each frame.

4. Damping (optional)

• *= 0.99 - This is multiplied with the velocity every frame, causing the planet to slow down very slightly each frame, giving it a friction-y feel
• x += vx - updates the position of the planet according to the velocity we computed

5. Draw everything

• noStroke() - no outline on the shapes.
• fill(100, 160, 255) - a blue colour for the planet. The colour is defined by RGB, red, green and blue where each value is 0-255.
• ellipse(x, y, 24, 24) - draws a circle at the planet's position, 24 pixels wide and 24 pixels tall. If the two numbers are different we would get a stretched circle (an ellipse), which is why this function is called ellipse
• The second ellipse draws a small yellow dot at your cursor to represent a star

Open index.html in your browser. You should see a blue planet orbiting your cursor!

6. Make it yours!

Sims that match the tutorial project won't be accepted! It needs to be unique in some way. Here are some ideas:

• Trail effect - instead of clearing the screen each frame, draw a semi-transparent background to leave a fading trail behind the planet.
• Multiple planets - spawn more planets that each orbit the cursor and pull on each other with gravity.
• Click to spawn - let the user click to add new planets, asteroids, or stars to the sim.
• Colour shifts - change the planet's colour based on its speed, distance from the cursor, or time.
• Particle effects - add tiny particles that trail behind the planet or burst out on collisions.
• Realistic physics - add mass to planets, use real gravitational constants, or simulate elastic collisions.
• UI controls - add sliders for gravity strength, planet size, damping, or number of bodies.

Deployment

Your sim needs a public URL so anyone can open it. The easiest way is GitHub Pages, although it won't work if you have server-side code (PHP, Python, etc.).

If you need a new repo:

1. Click the + in the top-right of GitHub and select New repository
2. Name it whatever you want
3. Make sure the visibility is set to Public
4. Click Create repository and upload your code to it

Enable GitHub Pages:

1. In your repo, go to Settings
2. In the sidebar under "Code and automation", click Pages
3. Under "Build and deployment", set the source to Deploy from a branch
4. Select main and / (root), then click Save
5. Wait a few minuites, then go to yourusername.github.io/repo-name to see your site!

Other hosting options work too, examples include Vercel, Netlify and Cloudflare Pages.

Submission

When your sim is live and you're ready to submit:

1. Fork the ORBIT repo
2. Open projects.json
3. Add your project to the array:

Field reference:

• title, author, url, repo - Add your project details! you can put your name or a username for 'author'.
• description - a short sentence shown in the project popup.
• country - your country as a 2-letter ISO code (US, GB, UA). Shows a flag in the popup. (optional).
• age - your age. Shows in the popup below the title. (optional).
• image - a screenshot of your sim. Accepts a URL (see below).

Adding a screenshot:

There are a couple of easy ways to get a hosted image URL:

• Hack Club Slack: Paste your image in the #cdn channel on the Hack Club Slack and you'll get a CDN URL back
• GitHub: If your'e not in the hack club slack you can open a GitHub issue on your repo, drop your screenshot into the comment box, and GitHub will give you a URL like https://user-images.githubusercontent.com/...

4. Open a pull request against main
5. We'll review it and merge it into the galaxy!

Resources

• p5.js tutorials - A good place to start if you're new
• Three.js manual - if you want to make a 3D sim
• NASA Open APIs - real space data and images
• NASA Image Library - free space textures and images
• Orbital mechanics basics - [text]

FAQ

Am I eligible?

If you're a teenager aged 13-18 (inclusive), yes!

This seems too good to be true, is Hack Club legit?

Yes! Hack Club is a legitimate 501(c)(3) nonprofit that has been supporting teenage coders since 2014. Previous You Ship, We Ship programmes include Sprig, OnBoard, and Blot

Is it free to participate?

Yes, completely free. You build something, we ship you prizes!

Can I use a game engine like Unity or Godot?

Yes, as long as the final result runs in a browser at a public URL. Godot exports to web. Unity's WebGL export can work too.

Does my project need to be open source?

Yes, your code needs a public GitHub repo.

I'm stuck and nothing works, how can I get help?

Post in the #orbit channel on the Hack Club Slack.