Skip to content

Commit

Permalink
Update README.md and other docs, Add devnotes.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@Capital-Asterisk @jonesmz
Capital-Asterisk authored and jonesmz committed Dec 9, 2024
1 parent b67b90b commit 548f32f
Show file tree
Hide file tree
Showing 6 changed files with 120 additions and 148 deletions.
147 changes: 47 additions & 100 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,59 +5,52 @@

![screenshot](screenshot0.png?raw=true "A Debug-rendered vehicle composed of parts flying over a planet.")

***This project is still deep in the pre-release development phase***
OpenSpaceProgram is an open source initiative with the goal of creating a realistic spacecraft building game inspired by Kerbal Space Program.

OpenSpaceProgram is an open source initiative with the goal of creating a space flight simulator inspired by Kerbal Space Program. This project also works as a general-purpose library for space games and simulations with very large universes and multiple planetary systems.
[[Website](https://openspaceprogram.org/)] [[Discord Server](https://discord.gg/7xFsKRg)]

Written in modern C++17, this project mainly features a custom game engine and a universe/orbit simulator, both relying on [EnTT](https://github.com/skypjack/entt/) and [Magnum](https://github.com/mosra/magnum). The universe and game engine are synchronized for a seamless spaceflight experience from a planet's surface to deep space.
Putting gameplay details aside (art, story, progression, etc...), a game of this nature requires a massive and complicated universe simulation with intricate vehicles, rigid-body physics, orbits, and literally rocket science. To avoid inevitably creating an unmaintainable buggy mess, we need a strong foundation built with considerable amounts of engineering and passion.

By taking advantage of Entity Component System (ECS) architectures and Data-Oriented Design, this project achieves simplicity, flexibility, low coupling, and excellent performance. With these techniques in action, we can easily avoid spaghetti code and optimize for a high part count.
***Introducing OSP-Magnum***

Goals:

* Fast, multi-threaded, and runs on everything
* Powerful API with mods / plugins
* Components reusable in other similar projects

After heavy iteration, it became apparent that it's impractical to build over an off-the-shelf game engine. Major components of OSP-Magnum (vehicles, planet terrain, code utilities, etc...) are designed as separate libraries that are usable on their own, independent of any game engine.

## Features

### Core

* Universe
* Support for Universes that use a hierarchical coordinate system, allowing sizes that can be described as:
* Big. Really big. You just won't believe how vastly, hugely, mindbogglingly big it is. I mean, you may think it's a long way down the road to the chemist's, but that's just peanuts.
* Arbitrary sized integers for coordinates within a particular layer of the hierarchy
* We use 64-bit integrer coordinates by default, but we're interested to see what people try out!
* Optimal data layout to support pluggable oribial mechanics algorithms, which includes
* Patched conics simulations -- like Kerbal Space Program's gameplay
* N-Body simulations -- like the KSP mod 'Principia'
* Build your own simulation logic!
* "ActiveScene" Game Engine
* Scene Graph
* Configurable multipass Renderer
* Straightforward interface for integrating any physics engine
* Out of the box we integrate with Newton Dynamics 3.14c.
* PRs to support other physics engines welcome!!!
* Wiring/Connection System
* Resource flow between ship components
* Fuel
* Cargo
* Life support
* Tell us about your ideas!
* Virtual control systems for vehicles
* routable user inputs
* PID
* auto-landing
* Write your own!
* Asset management
* Comes out of the box with glTF as a part model format
* Plugin-able ship part loader allowing arbitrary format support
* Extendable Bulleted List system to briefly present implemented features

### Extra

* *Newton Dynamics* Physics Engine integration
* Rockets, RCS, and Fuel tanks
* Rocket exhaust plume effects
* C++20
* Data-oriented design
* This basically means common data for multiple 'things' are often represented as big arrays instead of individual classes/objects
* Best utilizes the CPU you paid for, instead of being wasted by memory bottlenecks
* Simpler code, easier to multithread, and no overcomplicated inheritance hierarchy spaghetti
* Might be Entity-component-system???
* Scene Graph
* Jolt Physics integration
* Vehicles
* Part model format uses Standard glTF
* 'Link System' - Parts communicate like components in a logic circuit simulator. (PID control anything, differential thrust, auto-landing... Too many possibilities!)
* Planet terrain, Icosahedron-based tessellation
* Tasks and Framework utilities
* Runnable Test application demo
* OpenGL renderer using Magnum


Upcoming major features

* See https://github.com/TheOpenSpaceProgram/osp-magnum/issues?q=is%3Aissue+is%3Aopen+label%3Aplanned


### Test Application
Notes:

* No multi-threading is implemented yet
* Code is structured in a way that is easy to *efficiently* multithread in the future
* Don't underestimate how fast a single thread can be. This won't be a problem for a while

To act as a temporary menu and scenario loader, a console-based test application is implemented. It is **written in simple C++**, making it an excellent start to understanding the rest of the codebase.

## Building

Expand All @@ -82,77 +75,31 @@ cmake --build build-osp-magnum --parallel --config Release --target compile-test
ctest --schedule-random --progress --output-on-failure --parallel --no-tests error --build-config Release --test-dir build-osp-magnum/test
```

Run the game!
Run the testapp!

```bash
cd build-osp-magnum/Release
./osp-magnum
```

If you just want to test out the project so far, then see the [Actions](https://github.com/TheOpenSpaceProgram/osp-magnum/actions) tab on GitHub to obtain automated builds for Linux or Windows.

## Controls
These controls will seem familiar if you have played Kerbal Space Program!

#### Navigating
```bash
V - Switch game mode

ArrowUp - Camera look up
ArrowDown - Camera look down
ArrowLeft - Camera look left
ArrowRight - Camera look right

RightMouse - Camera orbit

W - Camera forward
S - Camera backwards
A - Camera left
D - Camera right

Q - Camera up
E - Camera down
```

#### Flight
```bash
S - Vehicle pitch up
W - Vehicle pitch down

A - Vehicle yaw left
D - Vehicle yaw right
This will bring up the "OSP-Magnum Temporary Debug CLI." From here you can enter commands to run a scenario, like `vehicles`.

Q - Vehicle roll left
E - Vehicle roll right

Z - Vehicle thrust max
X - Vehicle thrust min
LShift - Vehicle thrust increment
LCtrl - Vehicle thrust decrement

LCtrl+C | LShift+A - Vehicle self destruct
```

#### Misc
```bash
Space - Debug Throw
LCtrl+1 - Debug Planet Update
```
If you just want to try the demo without building, then see the [Actions](https://github.com/TheOpenSpaceProgram/osp-magnum/actions) tab on GitHub to obtain automated builds for Linux or Windows.

## Contributing

Our development team is very small right now. We need more crew to help to launch this project to its first release.

Join our [Discord Server](https://discord.gg/7xFsKRg) for the latest discussions. You *don't* need to be a professional C++ developer to be involved or help! Graphics, sounds, game design, and scientific accuracy are important to this project too.
You *don't* need to be a professional C++ developer to be involved or help! Graphics, sounds, game design, and scientific accuracy are important to this project too.

Checkout [Architecture.md](docs/architecture.md) to get started with learning the codebase. Feel free to ask questions (even, and especially, the stupid ones); this will greatly help with documentation.
### Resources

## Simplified development roadmap
* [Architecture.md](docs/architecture.md)
* [Framework Unit test / Tutorial](test/framework/main.cpp)
* [1 hour 30 minute long technical introduction video](https://www.youtube.com/watch?v=vdUllp9-E6k)
* [Informal project history from BDFL's perspective](https://gist.github.com/Capital-Asterisk/a22c81ffff1bf20d5023bdd40909d31d)

* Step 1: Make a space flight simulator
* Step 2: Bloat it with features
* Step 3: ???
* Step 4: Fun!
Feel free to ask questions on Github or Discord (even, and especially, the stupid ones); this will greatly help with documentation.

## Random Notes
* This project might be codenamed 'adera'. the name of the street the 49 UBC bus was at while the project files were first created.
Expand Down
31 changes: 22 additions & 9 deletions docs/architecture.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,15 +18,28 @@ Welcome aboard! This document presents a high level overview of the project, aim
## Directories

![Dependency graph](dependencygraph.png)
*osp-magnum ./src folder dependency graph. This visualizes how major components (each with their own directory) depend on each other. Some external dependencies are also shown (in pink)*

* `src/osp` - Core components for a spaceflight simulator.
* `src/adera` - Fun stuff. More gameplay and visual-effects focused.
* `src/planet-a` - Planet terrain subdivision code.
* `src/ospnewton` - Newton Dynamics physics engine integration
* `src/testapp` - Runnable application. Assembles everything to make test scenarios.

Most components are separate building blocks (with intended uses). The 'game engine' only comes into existence within `testapp`.
*osp-magnum ./src folder dependency graph between major components. Components depend on each other by `#include`-ing header files of another component.*

Legend:

* Light Blue - `src/osp` subdirectory. 'Main fundemental core stuff' library
* Dark Blue - Other subdirectories / libraries that are ours.
* Purple - External Libraries. Not our code.

Important notes:

* `osp/core` contains basic C++ stuff: containers, math, and utilities. Nothing space-related.
* [Magnum](https://github.com/mosra/magnum) (and its utility library Corrade) is used for their math and containers (i.e.: `Vector3` and `ArrayView`). Its OpenGL features are used only by `*_drawing_gl` and `testapp`.
* [EnTT](https://github.com/skypjack/entt/) is used for metaprogramming and containers. Its Entity-Component-System features (specifically entt::registry) are not used; they were used in OSP in the past, but the codebase has moved on since then.
* [Longeron++](https://github.com/Capital-Asterisk/longeronpp) Core components of OSP, but the BDFL decided to move them into a separate library.
* `osp/util` contains bigger (mostly self-contained) components that are intended for an application (not a library). So far this contains logging and user input processing.
* `osp/activescene` is your typical game engine 'scene graph'. This represents a 3D world of entities (ActiveEnt) that can be parented to each other and have physical properties.
* `osp/drawing` describes a set of entities (DrawEnt) that can be drawn; not specific to any rendering backend. (i.e.: A 'green cube' can be represented with DrawEnts, and it's up to whatever rendering backend we use to interpret that).
* `planet-a` generates planet terrain meshs. This code creates plain arrays of vertices and indices that are *intended* to be loaded into the physics engine or GPU, but doesn't have any of its own code for that.
* `ospjolt` integrates [Jolt Physics](https://github.com/jrouwe/JoltPhysics) to use as a rigid body physics engine for `osp/activescene`.
* `adera` is for fun stuff. More gameplay and visual-effects focused.
* `adera_app` gathers together many different components and uses `osp/framework` to package them into composable 'Features' to be used in an application.
* `src/testapp` sits at the top as a runnable application. Assembles everything to make test scenarios.

## Philosophy

Expand Down
55 changes: 32 additions & 23 deletions docs/dependencygraph.dot
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,56 +2,65 @@
// $ dot -Tpng docs/dependencygraph.dot -o docs/dependencygraph.png
digraph {

rankdir="BT"
rankdir="TB"
TBbalance="max"
bgcolor="#181122"
//bgcolor=transparent
node [color=transparent, fontcolor=white, fontname="Nimbus Sans bold"]
edge [color=white]

node [shape=rectangle, style=filled, fillcolor=palevioletred2]
node [shape=rectangle, style=filled, fillcolor=darkorchid4]
"EnTT"
"Longeron++"
"Magnum & Corrade"
"Magnum/GL";
"Newton Dynamics";
"Jolt Physics";
"Longeron++" [fillcolor="#003758"];

node [shape=rectangle, style=filled, fillcolor=white]

node [shape=rectangle, style=filled, fillcolor="#0276bc"]
"osp/core" -> "Magnum & Corrade";
"osp/core" -> "Longeron++";
"osp/core" -> "EnTT";
"osp/activescene" -> "osp/vehicles";
"osp/activescene" -> "osp/link";
"osp/drawing" -> "osp/activescene";
"osp/drawing_gl" -> "osp/drawing";
"osp/drawing_gl" -> "osp/util";
"osp/drawing_gl" -> "Magnum/GL";
"osp/link" -> "osp/core";
"osp/scientific" -> "osp/core";
"osp/tasks" -> "osp/core";
"osp/vehicles" -> "osp/scientific";
"osp/universe" -> "osp/core";
"osp/util" -> "osp/core";
"osp/framework" -> "osp/tasks";
"osp/framework" -> "osp/util";

node [shape=rectangle, style=filled, fillcolor=lightblue1]
node [shape=rectangle, style=filled, fillcolor="#003758"]

"adera/activescene" -> "osp/activescene";
"adera/drawing" -> "osp/activescene";
"adera/drawing_gl" -> "osp/drawing_gl";
"adera/drawing_gl" -> "osp/util";
"adera_drawing_gl" -> "osp_drawing_gl";
"osp_drawing_gl" -> "osp/drawing";
"osp_drawing_gl" -> "osp/util";
"osp_drawing_gl" -> "Magnum/GL";
"adera/machines" -> "osp/link";
"adera_app" -> "osp/framework";
"adera_app" -> "osp/universe";
"adera_app" -> "osp/tasks";
"adera_app" -> "adera/machines";
"adera_app" -> "adera/drawing";
"adera_app" -> "ospjolt";
"adera_app" -> "planet-a";
"adera_app" -> "adera/activescene";

node [shape=rectangle, style=filled, fillcolor=lightslateblue]
"ospnewton/activescene" -> "osp/activescene";
"ospnewton/activescene" -> "Newton Dynamics";
"ospjolt" -> "osp/activescene";
"ospjolt" -> "Jolt Physics";

node [shape=rectangle, style=filled, fillcolor=palegreen1]
"planet-a" -> "osp/core";

node [shape=rectangle, style=filled, fillcolor=orange1]
"testapp/sessions" -> "osp/universe";
"testapp/sessions" -> "osp/tasks";
"testapp/sessions" -> "adera/machines";
"testapp/sessions" -> "adera/drawing_gl";
"testapp/sessions" -> "adera/drawing";
"testapp/sessions" -> "ospnewton/activescene";
"testapp/sessions" -> "planet-a";
"testapp/sessions" -> "adera/activescene";
"testapp" -> "testapp/sessions";
node [shape=rectangle, style=filled, fillcolor="#fe9800"]
"testapp" -> "adera_app";
"testapp" -> "adera_drawing_gl";



Expand Down
Binary file modified docs/dependencygraph.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
19 changes: 19 additions & 0 deletions docs/devnotes.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Random development notes

A list of facts about the codebase in the current state of this commit; not quite practical to put into github issues.

## PSAs

To learn about `src/framework`, read `test/framework/main.cpp`


The pipeline executor in `src/osp/tasks/execute.*` (used by SingleThreadedExecutor in `src/osp/framework/executor.*`) is rather buggy. careful with it!
Likely worth making a new one. Make an executor that runs everything with a simpler and more correct algorithm. This might be slower and involve stuff like 'iterating all pipeline multiple times and seeing which ones can advance' but may be worth it for the correctness or having a ground truth reference for a more optimized one.


What is Sync/Resync???
* Synchronize GPU/rendering resources with whatever is in the scene. This might require GPU stuff for rendering but doesn't do any 'drawing'.
* Read things from the scene, and assign DrawEnts/textures/meshes/shaders to them
* ‘render’ might be skipped (pipeline cancelled), but important sync logic can still run
* Sync usually only iterates things when they change (using dirty flags / list of changes)
* Resync iterates everything. Used when changing scene or renderer.
16 changes: 0 additions & 16 deletions src/testapp/README.md
View file

This file was deleted.

0 comments on commit 548f32f

Please sign in to comment.