From 932b957a73a7f2e2a5dc84e78657060cf46e22a2 Mon Sep 17 00:00:00 2001 From: Lorenzo Torres Date: Mon, 17 Mar 2025 20:56:02 +0100 Subject: added documentation for contributors --- documentation/DESIGN | 49 +++++++++++++++++++++++++++++++++++++++++ documentation/STYLE | 58 +++++++++++++++++++++++++++++++++++++++++++++++++ documentation/TODO | 27 +++++++++++++++++++++++ documentation/design.md | 49 ----------------------------------------- 4 files changed, 134 insertions(+), 49 deletions(-) create mode 100644 documentation/DESIGN create mode 100644 documentation/STYLE create mode 100644 documentation/TODO delete mode 100644 documentation/design.md (limited to 'documentation') diff --git a/documentation/DESIGN b/documentation/DESIGN new file mode 100644 index 0000000..2f90d84 --- /dev/null +++ b/documentation/DESIGN @@ -0,0 +1,49 @@ +# Design +This document contains all the design decisions and features that are and will be implemented in the game. + +# Engine +## Rendering +The game engine uses Vulkan as the default graphics API but also implements an OpenGL backend for compatibility with older devices (some of them, while having Vulkan support, have better performance with OpenGL). +An abstraction over the graphics API allows clean utilization of the renderer in the engine, but also exposes a simple interface for mods. +glTF models are used for assets, but once loaded as the game starts, they are going to be converted to an internal intermediate representation format to increase loading performance. +A Metal backend might be implemented in the future for better MacOS integration. + +## Logic +An entity component system (ECS) internal API allows better usage of CPU cache lines while also providing a simple interface for the engine internals and mods. + +## OS interactions +The OS APIs are abstracted in a platform agnostic interface, used to make usual OS operations like opening files, creating network sockets, creating windows (X11, Wayland, Win32, Cocoa) and so on. + +## Mods +Modding is implemented using a custom Wasm (WebAssembly) virtual machine. The VM makes a sandbox for each mod so that they can't directly interact with each other nor accessing main memory or filesystem. +This safety features allow to download mods bytecode when joining a multiplayer game on the fly without worrying and without needing to install them locally before joining. +While not every language will be supported officaly, community projects can easily implement bindings for the engine modding API and then compile to a Wasm target. + +# Gameplay + +## Starting +When a new world is created, the players can choose in which biome they want to start their game. Depending on the biome, different resources and thus skills can be acquired. +For example, starting in a forest biome allows the players to gather a lot of woods, which can be traded with other players or used to build structures and tools. +Starting near waters (sea, lakes or rivers) can provide fast way of transportation with boats, fishing and direct access to drinkable water. +Every player starts with a small number of citizens and basic tools. + +## Citizens' health +After gathering enough resources, players must ensure that their citizens are happy and healthy: if they start to starve or freeze, they can decide to revolt and unless the player can manage to calm them (using military forces or with an agreement), the game will be over and the player will have to start over. + +## Diplomacy +Players can decide to be allied, neutral or enemies with each other and this state can change over the course of the game. By default all the players are neutral. +In case of an attack, players can ask for help to allies whether it's defensive or offensive. State borders are expanded by building structures in neutral territory, or by conquering other states. +When attacking a player, different ways of managing victory can be choosen: +- The defeated player can be taxed by the winner. +- The defeated player can keep independence, but must obey to the winner when receiving orders. +- The defeated player is completely destroyed and must restart the game. +In the first two cases, the winner can keep soldiers on the conquered territory and the defeated can try to revolt against the winner by fighting. + +## Attacking + +### Military training +Players can choose different ways of training soldiers: +- Every adult male will get at least some basic training and develop fighting skills. You will get a lot of soldiers, but with basic fighting skills. +- A group of regular citizens is selected and trained to develop average fighting skills. +- Specialized soldiers are trained full-time to develop quality fighting skills. In this case soldiers will need to be payed. +Note that enemies can only kill citizens who went through any level of training, otherwise they can only be enslaved. Since the number of slaves a winning player can make in an attack is limited, choosing the second or the third options can assure that at least some citizens will be left. diff --git a/documentation/STYLE b/documentation/STYLE new file mode 100644 index 0000000..989b2b1 --- /dev/null +++ b/documentation/STYLE @@ -0,0 +1,58 @@ +When contributing to Sideros, you should take account of this +style guide, which is mostly based on the Zig documentation +style guide (https://ziglang.org/documentation/0.14.0/#Style-Guide). + +1. Avoid these words in type names: + - Value + - Data + - Context + - Manager + - utils, misc, or somebody's initials + +Everything is a value, all types are data, everything is context, all logic manages +state. Nothing is communicated by using a word that applies to all types. +Temptation to use "utilities", "miscellaneous", or somebody's initials is a failure +to categorize, or more commonly, overcategorization. Such declarations can live at the +root of a module that needs them with no namespace needed. + +2. Avoid Redundant Names in Fully-Qualified Namespaces +Every declaration is assigned a fully qualified namespace by the compiler, creating a +tree structure. Choose names based on the fully-qualified namespace, and avoid redundant +name segments. For example, let's say you're writing a wrapping interface over WASM and +you need to create a structure to hold WebAssembly values. If you are importing that +file using `@import`, you will assign the code to a namespace, for example `wasm`. +For this reason, you should avoid calling your WASM value interface something like +`WasmValue`, because it will end up being used as `wasm.WasmValue`, just call it `Value` +and the code will be overall more readable (`wasm.Value`). + +3. Whitespaces + - 4 spaces for indentation + - Open braces on same line, unless you need to wrap + - If a list of things is longer than 2, put each item + on its own row and excercise the ability to put an + extra comma at the end. + - Aim for 100 as line length. + +4. Names + - for types, use "TitleCase", unless it's a namespace, + in that case use "snake_case". + - if x is callable, and returns a `type`, then use "TitleCase" + - if x is callable, and doesn't return a `type`, use "camelCase" + - everything else should be "snake_case" +Generally speaking, try to name things using easily understandable identifiers. +This can mostly be done by just writing names as full english words, and avoiding +acronyms and similar things. For example, prefer `time` over `t`, `speed` over `spd` +and so on. Just by doing this most of the code wouldn't need comments, because the +code will describe the logic by itself. + +5. Comments +Comments should never explain how code works, but rather how code should be used. +As stated in part 4, Zig has an explicit syntax allowing to write readable code, +just by using extended words for names and thus, in-code comments, explaining +how a specific part of code works, can be completely avoided. +Documentation comments, instead, can be very useful when exposing types and +functions, so that the behaviour of those can be easily read without going +to look directly at the source code. +The only exception is when the code logic can't be easily readable by +humans for optimization reasons (bitwise magic, for example) and so +in that case, in-code comments are allowed. diff --git a/documentation/TODO b/documentation/TODO new file mode 100644 index 0000000..77b4923 --- /dev/null +++ b/documentation/TODO @@ -0,0 +1,27 @@ +There are many things to implement in the game, here are listed some of them ranked by difficulty. + +EASY: + +- Writing a README file: +Currently, there is no README file, also because the project doesn't have a clear outline yet. + +- Code refactoring: +It's possible that sometimes code that doesn't conform to the style guidelines defined in STYLE will be pushed to the repository. +Finding that code, and fixing it so that it conforms to the guidelines would be a nice way of getting your hands +on the project for the first time and a big help to maintainers. + +- Documentation: +One of the goals of the project is to be as welcoming as possible to new contributions, this can't really be the case without good +documentation. Engine APIs, modding interfaces and modules of the code (rendering, vulkan, ecs, mods, ...) should be +documented with text files in `documentation/` and in the documentation page of the website (TODO). + +MEDIUM: + +- Implement internal windowing system: +The engine now uses GLFW to interface with the user's windowing system. But GLFW lacks flexibility and thus it might be better +to implement an internal abstraction to create windows and receive input, based on xcb for X11, wayland-client for Wayland, +Cocoa for MacOS and win32 for Windows. + +HARD: + + diff --git a/documentation/design.md b/documentation/design.md deleted file mode 100644 index 2f90d84..0000000 --- a/documentation/design.md +++ /dev/null @@ -1,49 +0,0 @@ -# Design -This document contains all the design decisions and features that are and will be implemented in the game. - -# Engine -## Rendering -The game engine uses Vulkan as the default graphics API but also implements an OpenGL backend for compatibility with older devices (some of them, while having Vulkan support, have better performance with OpenGL). -An abstraction over the graphics API allows clean utilization of the renderer in the engine, but also exposes a simple interface for mods. -glTF models are used for assets, but once loaded as the game starts, they are going to be converted to an internal intermediate representation format to increase loading performance. -A Metal backend might be implemented in the future for better MacOS integration. - -## Logic -An entity component system (ECS) internal API allows better usage of CPU cache lines while also providing a simple interface for the engine internals and mods. - -## OS interactions -The OS APIs are abstracted in a platform agnostic interface, used to make usual OS operations like opening files, creating network sockets, creating windows (X11, Wayland, Win32, Cocoa) and so on. - -## Mods -Modding is implemented using a custom Wasm (WebAssembly) virtual machine. The VM makes a sandbox for each mod so that they can't directly interact with each other nor accessing main memory or filesystem. -This safety features allow to download mods bytecode when joining a multiplayer game on the fly without worrying and without needing to install them locally before joining. -While not every language will be supported officaly, community projects can easily implement bindings for the engine modding API and then compile to a Wasm target. - -# Gameplay - -## Starting -When a new world is created, the players can choose in which biome they want to start their game. Depending on the biome, different resources and thus skills can be acquired. -For example, starting in a forest biome allows the players to gather a lot of woods, which can be traded with other players or used to build structures and tools. -Starting near waters (sea, lakes or rivers) can provide fast way of transportation with boats, fishing and direct access to drinkable water. -Every player starts with a small number of citizens and basic tools. - -## Citizens' health -After gathering enough resources, players must ensure that their citizens are happy and healthy: if they start to starve or freeze, they can decide to revolt and unless the player can manage to calm them (using military forces or with an agreement), the game will be over and the player will have to start over. - -## Diplomacy -Players can decide to be allied, neutral or enemies with each other and this state can change over the course of the game. By default all the players are neutral. -In case of an attack, players can ask for help to allies whether it's defensive or offensive. State borders are expanded by building structures in neutral territory, or by conquering other states. -When attacking a player, different ways of managing victory can be choosen: -- The defeated player can be taxed by the winner. -- The defeated player can keep independence, but must obey to the winner when receiving orders. -- The defeated player is completely destroyed and must restart the game. -In the first two cases, the winner can keep soldiers on the conquered territory and the defeated can try to revolt against the winner by fighting. - -## Attacking - -### Military training -Players can choose different ways of training soldiers: -- Every adult male will get at least some basic training and develop fighting skills. You will get a lot of soldiers, but with basic fighting skills. -- A group of regular citizens is selected and trained to develop average fighting skills. -- Specialized soldiers are trained full-time to develop quality fighting skills. In this case soldiers will need to be payed. -Note that enemies can only kill citizens who went through any level of training, otherwise they can only be enslaved. Since the number of slaves a winning player can make in an attack is limited, choosing the second or the third options can assure that at least some citizens will be left. -- cgit v1.2.3