neocrisis !

a collaborative coding game from NYC Python

Teaches: automation, JSON, REST APIs, Python, curl, httpie.

The earth is in danger!

We've detected multiple near earth objects (‘NEO’s) on a collision course with the earth. But we're not defenseless. Surrounding the earth we've launched multiple orbital defense platforms. It is your job to control these platforms and defend earth.

RULES

There are multiple objects (‘rocks’) spiralling toward the earth. Your orbital defense platforms (‘ODP’s) have telescopes and railguns. The telescopes can image the sky one ‘octant’ at a time. The railguns can fire ‘slugs’ to shoot down the ‘rocks.’

the earth is a point mass located at (0, 0, 0) in (x, y, z) space
orbital defense platforms are located at (0, 0, 0) in (x, y, z) space
- they orbit quickly enough that they can fire in any direction at any time
- they orbit quickly enough that they can image the sky in any direction at any time
each rock moves on a simple trajectory
- these trajectories are ballistic and inertialess (no thrust)
- these trajectories will spiral around the earth until impact
- they are unaffected by gravitational forces
- the trajectories are modelled by linear equations in spherical coördinates
each slug moves on a linear (straight line) trajectory from the earth
- slugs can be aimed in any direction
- these trajectories are ballistic and inertialess (no thrust)
- slugs cannot turn; they move in straight lines only
- the trajectories are modelled by linear equations in spherical coördinates
slugs collide only with other rocks
- slugs cannot collide with other slugs, and rocks cannot collide with other rocks
- if the rock has a mass of 1, then collision with a slug vaporizes both the rock and slug immediately
- if the rock has a mass greater than 1, then collision with a slug vaporizes the slug and rock but a rock fragment with smaller mass will be created

The orbital defense platforms can be controlled via JSON REST APIs. There are two endpoints.

The server can be found at: http://neocrisis.xyz

SELF-HELP QUICK START

# install https://httpie.org/
$ http get http://neocrisis.xyz/help/
$ http get http://neocrisis.xyz/telescope/help/
$ http get http://neocrisis.xyz/railgun/help/

JSON API

Instructions for how to request or send info to the server is below.

Verb	endpoint URL	params	description
GET	`/info`		gives information about the orbital weapon station
GET	`/telescope/<int:octant>`	`octant` from [1, 8]	images the specified `octant` (Ⅰ-Ⅷ) of the night sky and returns NEOs it sees
POST	`/railgun`	`name`, string (optional) `target`, string `phi`, number `theta`, number `fired`, string (optional)	fires a slug named `name` intending to hit `target` at the specified angles `theta` and `phi`, optionally specifying the future `fired` time at which to fire the slug as HH:MM:SS (for precise timing purposes)

The /telescope endpoint returns a JSON structure that looks like: { "objects": [ obj, … ] }

Each obj is a map with the following fields:

field	description
type	the tye of object: rock or slug
name	the name of the object
mass	the mass of the object
fired	when the rock was fired at the earth or when the slug was fired into space
pos	the spherical coördinates of the object at observation time
cpos	the Caresian coördinates of the object at observation time
obs_time	the observation time
octant	the octant (Ⅰ, Ⅱ, Ⅲ, Ⅳ, Ⅴ, Ⅵ, Ⅶ, Ⅷ) as an integer in which the object was spotted
age	the age of the object (how long it has been around since fired) in seconds

REST API EXAMPLE

Use curl or http (https://github.com/jakubroztocil/httpie/) to experiment with this API. Examples:

Take an image of octant one (Ⅰ) to search for objects.

$ http GET http://neocrisis.xyz/telescope/1

HTTP/1.0 200 OK
Content-Length: 20
Content-Type: application/json
Date: Wed, 4 Jul 2018 09:00:00 EST
Server: Werkzeug/0.14.1 Python/3.6.6

{
    "objects": [
        {
            "age": 3600,
            "cpos": {
                "x": 0.0,
                "y": 0.0,
                "z": 100.0,
            },
            "fired": "2018-07-04T08:00:00.000000-04:00",
            "mass": 2,
            "name": "99942 apophis",
            "obs_time": "2018-07-04T09:00:00.000000-04:00",
            "octant": 1,
            "pos": {
                "phi": 0.0,
                "r": 100.0,
                "theta": 0.0
            },
            "type": "rock"
        }
    ]
}

The above output shows one Near Earth Object: an asteroid (note the type ‘rock’) named ‘99942 apophis.’ It's on a direct course to hit the earth, unlike the real 99942 Apophis awhich has only a 2.7% chance of hitting earth on April 13, 2029 (https://en.wikipedia.org/wiki/99942_Apophis)

Next, we can fire a railgun slug at 99942 apophis. To better keep track of this new object, we can name it. We can name it anything we like. We'll name it ‘100 @ apophis’ to indicate what we intended to aim at.

$ http POST http://neocrisis.xyz/railgun name='100 @ apophis' theta:=0 phi:=0

HTTP/1.0 200 OK
Content-Length: 75
Content-Type: application/json
Date: Wed, 4 Jul 2018 09:00:01 EST
Server: Werkzeug/0.14.1 Python/3.6.6

{
    "slug": {
        "name": "100 @ apophis",
        "phi": 0.0,
        "theta": 0.0
    }
}

Image octant one (Ⅰ) again to see both the rock and the railgun slug we fired at it.

$ http GET http://neocrisis.xyz/telescope/1

HTTP/1.0 200 OK
Content-Length: 20
Content-Type: application/json
Date: Wed, 4 Jul 2018 09:00:05 EST
Server: Werkzeug/0.14.1 Python/3.6.6

{
    "objects": [
        {
            "age": 3600,
            "cpos": {
                "x": 0.0,
                "y": 0.0,
                "z": 95.0,
            },
            "fired": "2018-07-04T08:00:00.000000-04:00",
            "mass": 2,
            "name": "99942 apophis",
            "obs_time": "2018-07-04T09:00:05.000000-04:00",
            "octant": 1,
            "pos": {
                "phi": 0.0,
                "r": 95.0,
                "theta": 0.0
            },
            "type": "rock"
        },
        {
            "age": 4,
            "cpos": {
                "x": 0.0,
                "y": 0.0,
                "z": 4.0,
            },
            "fired": "2018-07-04T09:00:01.000000-04:00",
            "mass": 1,
            "name": "100 @ apophis",
            "obs_time": "2018-07-04T09:00:05.000000-04:00",
            "octant": 1,
            "pos": {
                "phi": 0.0,
                "r": 4.0,
                "theta": 0.0
            },
            "type": "slug"
        }
    ]
}

TRAJECTORIES, OCTANTS, and SPHERICAL COÖRDINATES

See docs/trajectories.pdf for more information.

The position of slugs and rocks can be described in terms of Cartesian coördinates (x, y, z) or spherical coördinates (r, θ, φ).

Our convention for Cartesian coördinates `(x, y, z)` is as follows:

Cartesian coördinate	measures	range & units	directional convention
`x`	distance	[0, ∞) meters	from the earth's core toward the 0° Prime Meridian (Greenwich, UK)
`y`	distance	[0, ∞) meters	from the earth's core toward the 90° meridian (Memphis, TN)
`z`	distance	[0, ∞) meters	from the earth's core toward 0° latitutde (North Pole)

Note that our convention is left-handed, as opposed to the traditional right-handed coordniate system seen the graphics below. This is because our positive y direction is west, instead of east; in other words, their +y is our -y.

Our convention for spherical coördinates `(r, θ, φ)` is as follows:

spherical coördinate	measures	range & units	directional convention
`r` ‘radius’	distance	[0, ∞) meters	from the earth's core toward outer space
`θ` ‘theta’, ‘azimuth’	angle	[0, 2π] radians	east-to-west (longitudinally) from the 0° Prime Meridian (Greenwich, UK) toward the 90° meridian (Memphis, TN)
`φ` ‘phi’, ‘inclination’	angle	[0, π] radians	north-to-south (latitudinally) from the North Pole to the South Pole

Our convention for octant numbers is as follows:

number	roman numeral	`x`-sign	`y`-sign	`z`-sign
1	I	`+`	`+`	`+`
2	II	`-`	`+`	`+`
3	III	`-`	`-`	`+`
4	IV	`+`	`-`	`+`
5	V	`+`	`+`	`-`
6	VI	`-`	`+`	`-`
7	VII	`-`	`-`	`-`
8	VIII	`+`	`-`	`-`

The trajectories of rocks and slugs follow the below equations:

NEO	params	r	phi	theta
slugs	`v` velocity `phi` fixed at fire time `theta` fixed at fire time	`r = v × t`	`phi`	`theta`
rocks	`v` velocity `r_₀` initial radius `m_φ` phi-slope `b_φ` phi-intercept `m_θ` theta-slope `b_θ` theta-intercept	`r = v × t + r₀`	`phi = m_φ × t + b_φ`	`theta = m_θ × t + b_θ`

The position of an object is determined only by its parameters and t, time.

MATH HELP and HINTS

Hints:

the above equations are independent of each other: r, phi, and theta do not affect each other.
for the rocks, each equation has only two unknowns; therefore, you only need to take two measurements to determine the unknowns

To compute the trajectory of a rock, take two measurements of its position in spherical coördinates (r, θ, φ).

Two measurements are taken at t₁ and t₂.
- call them (r₁, phi₁, theta₁) and (r₂, phi₂, theta₂)
We want to solve for v_rock and r₀. Note: unlike a real asteroid, these asteroids' distances to the earth vary linearly. You need only basic algebra to determine a firing solution. No calculus is needed. They do not accelerate: their velocities are constant at all times.
- we know that r₁ = v_rock × t₁ + r₀ and r₂ = v_rock × t₂ + r₀
- therefore, v = (r₁ - r₂) ÷ (t₁ - t₂)
- therefore, r₀ = r₁ - v_rock × t₁ or r₀ = r₂ - v_rock × t₂
- Remember, velocity is a vector (signed) quantity! Since the rock is moving TOWARDS the origin (in other words, r_rock(t) is becoming smaller over time), its velocity will be negative
We also want to solve for m_φ and b_φ.
- we know that phi₁ = m_φ × t₁ + b_φ and phi₂ = m_φ × t₂ + b_φ
- therefore, m_φ = (phi₁ - phi₂) ÷ (t₁ - t₂)
- therefore, b_φ = phi₁ - m_φ × t₁ or b_φ = phi₂ - m_φ × t₂
Finally, we want to solve for m_θ and b_θ.
- we know that theta₁ = m_θ × t₁ + b_θ and theta₂ = m_θ × t₂ + b_θ
- therefore, m_θ = (phi₁ - phi₂) ÷ (t₁ - t₂)
- therefore, b_θ = phi₁ - m_θ × t₁ or b_θ = phi₂ - m_θ × t₂
We need to compute direction in which to fire the slug; its phi and theta angles
- we're given the slug's v_slug velocity
- we know that at collision time t_collide, that r_rock and r_slug will be the same: r_slug = r_rock = r_collide
- we know r_collide = v_rock × t_{collide + r₀} and r_{slug, collide} = v_slug × t_collide
- therefore, t_{collide = r₀ ÷ (v_rock - v_slug)}
- knowing the collision time, we can determine the firing angles
- therefore, phi_collide = m_φ × t_collide + b_φ and theta_collide = m₀ × t_collide + b₀

Altogether:

    # solve for v and r₀

    v = (r₁ - r₂) ÷ (t₁ - t₂)
    r₀ = r₁ - v × t₁
    r₀ = r₂ - v × t₂

    # solve for m_φ and b_φ 

    m_φ = (phi₁ - phi₂) ÷ (t₁ - t₂)
    b_φ = phi₁ - m_φ × t₁, b_φ = phi₂ - m_φ × t₂

    # solve for m_θ and b_θ 

    m_θ = (phi₁ - phi₂) ÷ (t₁ - t₂)
    b_θ = phi₁ - m_θ × t₁, b_θ = phi₂ - m_θ × t₂

    # solve for t_collide 

    t_collide = r₀ ÷ (v_rock - v_slug)

    # solve for phi_collide and theta_collide 

    phi_collide = m_φ × t_collide + b_φ
    theta_collide = m₀ × t_collide + b₀

CODE and IMPLEMENTATOIN

game engine

The game engine lives entirely in the data model of a Postgres database.

the data model is at engine/model.sql
sample (test) data can be found at engine/data.sql
simple smoke tests (using the sample data) can be found at engine/checks.sql
the data model is made bitemporal via engine/bitemporal

There are two schemas:

game which contains the game core data
api which contains views used by the API

The major tables are:

game.rocks which contains all rocks for a given game (incl. those that have collided with a slug or the earth)
game.slugs which contains all slugs for a given game (incl. those that have collided with a rock)
game.collisions which contains all collisions between all rocks and all slugs (rocks × slugs); the collision column represents the state of the collision
game.hits which contains all of the hits (every computed hit of a slug and a rock)

The collision composite type represents the result of a collision computation. Its fields include:

t, the time at when the collision would have occurred (or null if no collision was possible)
pos, the position at which the collision would have occured (or null)
mdiff, the difference in position between the slug and rock if there was a miss (or null if there was a hit)
miss, an enum field with the reason for the miss — r didn't match, theta didn't match, and/or phi didn't match (or null if there was a hit)

The game.collisions and game.hits tables are populated by triggers.

upon insert/update to game.rocks or game.slugs, recompute all collisions and insert/update in game.collisions
upon insert/update/delete to game.collisions, recompute all hits and delete/insert in game.hits
upon insert to game.hits, compute and rock fragments and insert into game.rocks (potentially “cascading” triggers)

The major views in api are:

api.rocks whch contains all rocks (incl. those that have collided) with positions and other derived fields computed
api.slugs whch contains all slugs (incl. those that have collided) with positions and other derived fields computed
api.all_neos which contains a union of all rocks and slugs (incl. those that have collided)
api.neos which contains a union of all active rocks and slugs (not incl. those that have collided)
api.collisions which contains all collisions (whether hits or missed) inner-joined nicely with game.rocks and game.slugs to include display names
api.hits which contains all collisions (whether hits or missed) inner-joined nicely with game.rocks and game.slugs to include display names

REST API

The REST API is a single-file flask (https://github.com/pallets/flask) app.

You can find it at api/api.py.

sample scripts

You can find some sample scripts in examples/.

examples/observer.py images the night sky in a loop and reports what it finds
examples/autofire.py is a sample automated defense system that scans and automatically fires at every object it sees

MEETUPS

neocrisis is a collaborative coding game created by the folks behind NYC Python! It has been played at the following events:

Submit a PR to list any events where you've played NEO Crisis.

Name		Name	Last commit message	Last commit date
Latest commit History 130 Commits
api		api
data		data
deploy		deploy
docs		docs
engine		engine
examples		examples
game		game
.gitignore		.gitignore
README.md		README.md
Vagrantfile		Vagrantfile

dutc/neocrisis

Folders and files

Latest commit

History

Repository files navigation

neocrisis !

a collaborative coding game from NYC Python

RULES

SELF-HELP QUICK START

JSON API

REST API EXAMPLE

TRAJECTORIES, OCTANTS, and SPHERICAL COÖRDINATES

Our convention for Cartesian coördinates (x, y, z) is as follows:

Our convention for spherical coördinates (r, θ, φ) is as follows:

Our convention for octant numbers is as follows:

The trajectories of rocks and slugs follow the below equations:

MATH HELP and HINTS

CODE and IMPLEMENTATOIN

game engine

REST API

sample scripts

MEETUPS

CREDITS and COPYRIGHT

About

Resources

Stars

Watchers

Forks

Languages

Our convention for Cartesian coördinates `(x, y, z)` is as follows:

Our convention for spherical coördinates `(r, θ, φ)` is as follows: