
The Pitch
Getting Started
How it Works
Testing
Zen
Philosophical decisions. All code should align with them without exceptions.
- If recovery is impossible a crash is warranted. If a specific error is not possible to recover from in a given context the program should crash with appropriate message.
- All sad paths should be signposted. For every function that can crash it should have error states clearly defined (e.g. returning a null pointer). Alternatively, it should supply all precautions
- OOM is not a recoverable error. If the program runs out of memory it can only crash. The memory is meticolously managed so running out of memory is either reaching the machine's limitations or a programmer error.
- Trivially terminating loops. All loops should have a trivial, reachable and proveable termiation condition. If the loop should, ideally, run forever (i.e. hash chaining), it should have a maximum iteration limit.
- No stack recursion. A function should never recurse, partially because then its more difficult to verify.
- Free memory is poisoned. The memory handled by an allocator before being given to the program should always be poisoed. This ensures that only the memory that is intended to be used by the program is actually used.
Conventions
The code and the documentation both use a lot of specific conventions. The project is written in C and is doing its best to avoid memory leaks, buffer overflows and so on.
- The code is riddled with
ASSERT
s. That's good.
- Everything is
snake_case
, unless its trying to mimic another notation. For instance, glMessageCallback
is trying to copy OpenGL, so its an exception.
- All structure types are postfixed with
_t
except algebraic ones (vec2
, vec2i
, mat4
, etc).
- Callback types are postfixed with
_f
instead of _t
.
- All member functions of a type are prefixed with the name without a postfix, like
scheduler_plan
for scheduler_t
and vec2_new
for vec2
.
- For a
T
there can exist constructors T T_new(...)
, void T_init(T* self, ...)
or both.
T_new
does not allocate dynamic resources, T_init
does.
- If a type manages dynamic resources it will have a destructor
void T_cleanup(T* self)
.
- If a type is a sum-type (i.e. union of structs with an enum identifier), the
_new
family will expose all possible kinds as their own constructors (T_new_foo
, T_new_bar
and so on).
- Double underscores in method names usually mean "private".
- Single underscores in the beginning of a field name also mean "private".
U_as_V
marks a reference cast, the U
must be valid for V
to be valid.
U_to_V
marks an independent cast. The U
is valid on its own.
U_into_V
marks a destructive cast, the U
is no longer valid and does not need to be cleaned up.
- In the context of the
O(N)
notation, N
and M
are big constants with M ≤ N
if applicable.
- Similarly,
n
and m
are small constants relative to N
and M
.
//
are a functionality comment, ///
are documenting comments.
Credits
Coded by Artur Roos. Available on GitHub. What follows is a list of technologies that are important to this project in no particular order.
- OpenGL, the rendering API.
- cc65 Toolchain, a full-on compiler/assembler/linker for the 6502.
- Doxygen, a documentation generation tool.
- Markdown, the fanstastic human-readable markup language.
- Just, a Make-like quick command runner.
- Python, the tool more complex scripting.
- Git, the version control system.
- Aseprite, the best pixel art editor ever.
- Clang, the best C compiler under the sun.
xxd
, the hexdump utility.
ripgrep
, a faster grep
.
stb_image.h
, a header-only public domain library for reading image data.
The following is a looser list of things that were inspirational to the technical aspects of the project.
- Factorio, an addictive game about building the factories.
- Screeps.io, a JavaScript game where you control small agents with code.
- ComputerCraft, a Minecraft mod where you program computers with Lua.
License
This project is distributed under the strong copyleft AGPL-3.0
license. If you make something using this project it also must be AGPL-3.0, kinda. Not a lawyer, this is not legal advice.
Contributing
Contact