diff --git a/classcubos_1_1core_1_1memory_1_1ReadGuard.html b/classcubos_1_1core_1_1memory_1_1ReadGuard.html index 1dff65b14..424154145 100644 --- a/classcubos_1_1core_1_1memory_1_1ReadGuard.html +++ b/classcubos_1_1core_1_1memory_1_1ReadGuard.html @@ -67,7 +67,7 @@

-

This class was created because there are multiple parts of the code that need to provide access to objects in a thread-safe manner.

Usage example

using AssetMetaRead = core::memory::ReadGuard<AssetMeta, std::shared_lock<std::shared_mutex>>;
+

This class was created because there are multiple parts of the code that need to provide access to objects in a thread-safe manner.

Usage example

using AssetMetaRead = core::memory::ReadGuard<AssetMeta, std::shared_lock<std::shared_mutex>>;

Constructors, destructors, conversion operators

diff --git a/classcubos_1_1core_1_1memory_1_1Stream.html b/classcubos_1_1core_1_1memory_1_1Stream.html index af7ec18a4..8ffd493d7 100644 --- a/classcubos_1_1core_1_1memory_1_1Stream.html +++ b/classcubos_1_1core_1_1memory_1_1Stream.html @@ -51,7 +51,7 @@

-

Motivation

Why do we have our own streams? Well, the standard library streams are hard to use and extend, and very template heavy. Using our own streams allows us to abstract away more easily where the data is coming from, or going to, allowing us, for example, to embed files into the executable and not have to worry about the code that reads them.

+

Motivation

Why do we have our own streams? Well, the standard library streams are hard to use and extend, and very template heavy. Using our own streams allows us to abstract away more easily where the data is coming from, or going to, allowing us, for example, to embed files into the executable and not have to worry about the code that reads them.

Derived classes

@@ -652,7 +652,7 @@

-

Usage
stream.printf("Hello, {}!\n", "world");
+
Usage
stream.printf("Hello, {}!\n", "world");
 stream.printf("{} + {} = {}\n", 1, 2, 3);
 stream.printf("\\{} {}\n", 1, 2); // This will print "{} 2"
diff --git a/classcubos_1_1core_1_1memory_1_1WriteGuard.html b/classcubos_1_1core_1_1memory_1_1WriteGuard.html index 4bc44fb2d..724358a03 100644 --- a/classcubos_1_1core_1_1memory_1_1WriteGuard.html +++ b/classcubos_1_1core_1_1memory_1_1WriteGuard.html @@ -67,7 +67,7 @@

-

This class was created because there are multiple parts of the code that need to provide access to objects in a thread-safe manner.

Usage example

using AssetMetaWrite = core::memory::WriteGuard<AssetMeta, std::unique_lock<std::shared_mutex>>;
+

This class was created because there are multiple parts of the code that need to provide access to objects in a thread-safe manner.

Usage example

using AssetMetaWrite = core::memory::WriteGuard<AssetMeta, std::unique_lock<std::shared_mutex>>;

Constructors, destructors, conversion operators

diff --git a/contribution.html b/contribution.html index 5fbe78dfd..44c122394 100644 --- a/contribution.html +++ b/contribution.html @@ -47,7 +47,18 @@

Contribution guidelines

Guide on the project's conventions and code style.

-

+

Commits

Commits should be concise and small, such that they are easy to review. Avoid at all costs including non-related changes in a commit - use git add -p or something similar to force yourself to review the changes you are commiting, and to avoid accidentally commiting unrelated changes.

Commits should follow Conventional Commits and be written in imperative mood. We use the scopes core, engine and tools. When making a commit which affects more than one of these scopes, you can ommit the scope.

If your description is too long, you can add a body to the commit message. The body should be separated from the description by a blank line.

Examples of good commit messages:

feat(core): add CUBOS_FAIL, CUBOS_UNREACHABLE and CUBOS_DEBUG_ASSERT 
+test(core): move filesystem tests to data/fs
+fix(core): fix segfault when popping a sub context
+feat(engine): implement system for sweeping the markers  
+docs(engine): add comments to colliders
+chore: replace GoogleTest submodule with doctest

Examples of bad commit messages:

fix: fix bug
+make it work
+feat(core): Add CUBOS_FAIL
+docs(engine): added comments to colliders

Pull Requests

Pull requests should be concise and small, and if needed, split into multiple smaller PRs so that they are easier to review. If your PR is still not finished, mark it as a draft. When working on new features, draft PRs should be created so that other contributors can have an idea of what is being worked on.

Any features added in a PR should be covered by tests and documentation, including new examples demonstrating the feature.

Documentation

We use Doxygen for documentation, which means that the documentation is mostly written in the code itself. When adding new files, classes, functions, etc, make sure to at least add a triple slash comment (///) with a @brief section describing what it does, otherwise Doxygen will omit it from the documentation.

Make sure to document all function parameters, template parameters and return values. Take a look at other files to get a grasp of the documentation style we use.

When changing the code, the documentation should be updated accordingly.

Plugins

Engine plugins should document which components and resources they add, which tags and settings are used, and how to use them. Take a look at the documentation of other plugins such as the renderer plugin to get an idea of how it should look like.

Every type or function that is part of the public API of a plugin should be added to its corresponding group in the Doxygen documentation, using the @ingroup tag.

Code Style

Casing

We use camelCase for functions, methods, local variables and fields. Private fields are prefixed with m (e.g. mMyField). PascalCase is used for class names and constants. UPPER_CASE is used for macros. snake_case is used for namespaces, folders and files.

Formatting

Code is formatted using clang format. Although we have an action that runs clang format on every PR, it is recommended that you run it locally before commiting your changes, to make it easier for the reviewers to read your code.

We also check the code with clang tidy, which is a static analysis tool which picks up many common mistakes and code smell. This runs on every commit you push to your branch.

Macros

Avoid using macros whenever possible - use constexpr variables or functions instead. If you do need to use a macro to make an implementation more readable, restrict the macro to the source file where it is used. Defining macros in header files is heavily discouraged.

Namespaces

Avoid using namespace in header files. In source files, prefer using foo::bar::X over using namespace foo::bar. If your code is under the namespace foo::bar, you can use using namespace foo::bar in the source files, to make the code more readable.

When closing a namespace the namespace name should be added as a comment. E.g.:

namespace foo
+{
+    ...
+} // namespace foo
diff --git a/group__asset-explorer-tool-plugin.html b/group__asset-explorer-tool-plugin.html index a428baa9d..7e51c5135 100644 --- a/group__asset-explorer-tool-plugin.html +++ b/group__asset-explorer-tool-plugin.html @@ -51,8 +51,8 @@

-

Events

Dependencies

+

Events

Dependencies

Files

diff --git a/group__assets-plugin.html b/group__assets-plugin.html index db6134976..3b990beaf 100644 --- a/group__assets-plugin.html +++ b/group__assets-plugin.html @@ -50,11 +50,11 @@

-

Settings

  • assets.io.enabled - whether asset I/O should be done (default: true).
  • assets.io.path - path to the assets directory - will be mounted to /assets/ (default: assets/).
  • assets.io.readOnly - if true, the assets directory will be mounted as read-only (default: true).

Events

  • AssetEvent - (TODO) emitted when an asset is either loaded, modified or unloaded.

Resources

  • Assets - the asset manager, used to access asset data.

Startup tags

  • cubos.assets.init - initializes the assets manager and loads the meta files (after cubos.settings).
  • cubos.assets.bridge - systes which add bridges to the asset manager should be tagged with this.
  • cubos.assets - systems which load assets should be tagged with this.

Tags

  • cubos.assets.cleanup - frees any assets no longer in use.
+

Settings

  • assets.io.enabled - whether asset I/O should be done (default: true).
  • assets.io.path - path to the assets directory - will be mounted to /assets/ (default: assets/).
  • assets.io.readOnly - if true, the assets directory will be mounted as read-only (default: true).

Events

  • AssetEvent - (TODO) emitted when an asset is either loaded, modified or unloaded.

Resources

  • Assets - the asset manager, used to access asset data.

Startup tags

  • cubos.assets.init - initializes the assets manager and loads the meta files (after cubos.settings).
  • cubos.assets.bridge - systes which add bridges to the asset manager should be tagged with this.
  • cubos.assets - systems which load assets should be tagged with this.

Tags

  • cubos.assets.cleanup - frees any assets no longer in use.

Files

diff --git a/group__collisions-plugin.html b/group__collisions-plugin.html index 587891a4c..3b879506e 100644 --- a/group__collisions-plugin.html +++ b/group__collisions-plugin.html @@ -50,11 +50,11 @@

-

Components

Events

  • CollisionEvent - (TODO) emitted when a collision occurs.
  • TriggerEvent - (TODO) emitted when a trigger is entered or exited.

Resources

Tags

  • cubos.collisions.aabb.missing - missing aabb colliders are added.
  • cubos.collisions.aabb - collider aabbs are updated.
  • cubos.collisions.broad.markers - sweep markers are updated.
  • cubos.collisions.broad.sweep - sweep is performed.
  • cubos.collisions.broad - broad phase collision detection.
  • cubos.collisions - collisions are resolved.

Dependencies

+

Components

Events

  • CollisionEvent - (TODO) emitted when a collision occurs.
  • TriggerEvent - (TODO) emitted when a trigger is entered or exited.

Resources

Tags

  • cubos.collisions.aabb.missing - missing aabb colliders are added.
  • cubos.collisions.aabb - collider aabbs are updated.
  • cubos.collisions.broad.markers - sweep markers are updated.
  • cubos.collisions.broad.sweep - sweep is performed.
  • cubos.collisions.broad - broad phase collision detection.
  • cubos.collisions - collisions are resolved.

Dependencies

Files

diff --git a/group__core-ecs.html b/group__core-ecs.html index 3b115f7b7..dfed4083d 100644 --- a/group__core-ecs.html +++ b/group__core-ecs.html @@ -50,9 +50,9 @@

-

This module is arguably the heart of the engine, as it provides a means to organize and manage the data and logic of both the engine and games built with it. It is, as of now, a bit of a mess. Most of the exposed types are internal to the documentation, and thus it can get hard to navigate (TODO #377).

Data types

  • World - stores entities, components and resources, can be queried.
  • Dispatcher - stores and dispatches systems in the right order.
  • Blueprint - bundle of entities and components which can be spawned using Commands.

System argument types

  • Read<R> - used to read resource data of type R.
  • Write<R> - used to write resource data of type R.
  • Read<World> - used to read the world directly (not recommended, ruins parallelism, prefer Commands).
  • Write<World> - used to write the world directly (not recommended, ruins parallelism, prefer Commands).
  • Commands - used to queue entities to be created, destroyed and other operations.
  • EventReader<E> - reads events of type E sent from other systems.
  • EventWriter<E> - sends events of type E to other systems.
  • Query<Args...> - queries the world for entities which match its arguments.

Query argument types

  • Read<C> - matches entities with the component C, read-only access.
  • Write<C> - matches entities with the component C, write access.
  • OptRead<C> - matches all entities, read-only access when the component C is present.
  • OptWrite<C> - matches all entities, write access when the component C is present.
+

This module is arguably the heart of the engine, as it provides a means to organize and manage the data and logic of both the engine and games built with it. It is, as of now, a bit of a mess. Most of the exposed types are internal to the documentation, and thus it can get hard to navigate (TODO #377).

Data types

  • World - stores entities, components and resources, can be queried.
  • Dispatcher - stores and dispatches systems in the right order.
  • Blueprint - bundle of entities and components which can be spawned using Commands.

System argument types

  • Read<R> - used to read resource data of type R.
  • Write<R> - used to write resource data of type R.
  • Read<World> - used to read the world directly (not recommended, ruins parallelism, prefer Commands).
  • Write<World> - used to write the world directly (not recommended, ruins parallelism, prefer Commands).
  • Commands - used to queue entities to be created, destroyed and other operations.
  • EventReader<E> - reads events of type E sent from other systems.
  • EventWriter<E> - sends events of type E to other systems.
  • Query<Args...> - queries the world for entities which match its arguments.

Query argument types

  • Read<C> - matches entities with the component C, read-only access.
  • Write<C> - matches entities with the component C, write access.
  • OptRead<C> - matches all entities, read-only access when the component C is present.
  • OptWrite<C> - matches all entities, write access when the component C is present.

Files

diff --git a/group__entity-inspector-tool-plugin.html b/group__entity-inspector-tool-plugin.html index e6ac4bfdd..447026053 100644 --- a/group__entity-inspector-tool-plugin.html +++ b/group__entity-inspector-tool-plugin.html @@ -51,7 +51,7 @@

-

Dependencies

+

Dependencies

Files

diff --git a/group__entity-selector-tool-plugin.html b/group__entity-selector-tool-plugin.html index b48d355b2..6d6bdceea 100644 --- a/group__entity-selector-tool-plugin.html +++ b/group__entity-selector-tool-plugin.html @@ -51,7 +51,7 @@

-

This plugins exists to reduce coupling between plugins. For example, a plugin which allows selecting entities through a ImGui window only needs to depend on this plugin, instead of having to know about all the plugins which care about it. The same applies in the other direction.

Resources

+

This plugins exists to reduce coupling between plugins. For example, a plugin which allows selecting entities through a ImGui window only needs to depend on this plugin, instead of having to know about all the plugins which care about it. The same applies in the other direction.

Resources

Files

diff --git a/group__env-settings-plugin.html b/group__env-settings-plugin.html index 1bfed6f6e..5aabfc136 100644 --- a/group__env-settings-plugin.html +++ b/group__env-settings-plugin.html @@ -50,7 +50,7 @@

-

This plugin needs the Arguments resource, and thus, the constructor Cubos::Cubos(int, char**) must be used to construct the application. Any previous setting will be overwritten if its set on the arguments.

Startup tags

  • cubos.settings - the settings are loaded.
  • cubos.settings.env - the settings are loaded.
+

This plugin needs the Arguments resource, and thus, the constructor Cubos::Cubos(int, char**) must be used to construct the application. Any previous setting will be overwritten if its set on the arguments.

Startup tags

  • cubos.settings - the settings are loaded.
  • cubos.settings.env - the settings are loaded.

Files

diff --git a/group__file-settings-plugin.html b/group__file-settings-plugin.html index c079c9ed5..d02e9812b 100644 --- a/group__file-settings-plugin.html +++ b/group__file-settings-plugin.html @@ -50,8 +50,8 @@

-

The settings file must be a JSON file. If the file does not exist or can't be parsed, the plugin aborts. Any previously set setting will be overwritten if its set on the file.

Settings

  • settings.path - path of the settings file (default: ./settings.json).

Startup tags

  • cubos.settings - the settings are loaded.
  • cubos.settings.file - the settings are loaded.
+

The settings file must be a JSON file. If the file does not exist or can't be parsed, the plugin aborts. Any previously set setting will be overwritten if its set on the file.

Settings

  • settings.path - path of the settings file (default: ./settings.json).

Startup tags

  • cubos.settings - the settings are loaded.
  • cubos.settings.file - the settings are loaded.

Files

diff --git a/group__imgui-plugin.html b/group__imgui-plugin.html index f74d29192..ea8312e4b 100644 --- a/group__imgui-plugin.html +++ b/group__imgui-plugin.html @@ -50,9 +50,9 @@

-

Startup tags

  • cubos.imgui.init - ImGui is initialized, after cubos.window.init.

Tags

  • cubos.imgui.begin - the ImGui frame begins (after cubos.window.poll).
  • cubos.imgui.end - the ImGui frame ends (before cubos.window.render).
  • cubos.imgui - runs between the previous two tags.

Dependencies

+

Startup tags

  • cubos.imgui.init - ImGui is initialized, after cubos.window.init.

Tags

  • cubos.imgui.begin - the ImGui frame begins (after cubos.window.poll).
  • cubos.imgui.end - the ImGui frame ends (before cubos.window.render).
  • cubos.imgui - runs between the previous two tags.

Dependencies

Files

diff --git a/group__input-plugin.html b/group__input-plugin.html index 8359fb70b..79a833c5b 100644 --- a/group__input-plugin.html +++ b/group__input-plugin.html @@ -50,11 +50,11 @@

-

Bridges

Events

  • InputEvent - (TODO) emitted when an input event occurs.

Resources

  • Input - stateful input manager, used to query the input state.

Tags

  • cubos.input.update - updates the input state.

Dependencies

+

Bridges

Events

  • InputEvent - (TODO) emitted when an input event occurs.

Resources

  • Input - stateful input manager, used to query the input state.

Tags

  • cubos.input.update - updates the input state.

Dependencies

Files

diff --git a/group__renderer-plugin.html b/group__renderer-plugin.html index c6c9364ca..0c1c76520 100644 --- a/group__renderer-plugin.html +++ b/group__renderer-plugin.html @@ -50,12 +50,12 @@

-

Renders all entities with the RenderableGrid component, using as cameras entities with the Camera component selected by the ActiveCameras resource. Lights are rendered using entities with SpotLight, DirectionalLight or PointLight components.

The rendering environment, such as the ambient lighting and sky color, can be set through the resource RendererEnvironment.

Settings

  • cubos.renderer.ssao.enabled - whether SSAO is enabled.

Resources

Components

Startup tags

  • cubos.renderer.init - the renderer is initialized, after cubos.window.init.

Tags

  • cubos.renderer.frame - frame information is collected, after cubos.transform.update.
  • cubos.renderer.draw - frame is rendered to the window, after cubos.renderer.frame and before cubos.window.render.

Dependencies

+

Renders all entities with the RenderableGrid component, using as cameras entities with the Camera component selected by the ActiveCameras resource. Lights are rendered using entities with SpotLight, DirectionalLight or PointLight components.

The rendering environment, such as the ambient lighting and sky color, can be set through the resource RendererEnvironment.

Settings

  • cubos.renderer.ssao.enabled - whether SSAO is enabled.

Resources

Components

Startup tags

  • cubos.renderer.init - the renderer is initialized, after cubos.window.init.

Tags

  • cubos.renderer.frame - frame information is collected, after cubos.transform.update.
  • cubos.renderer.draw - frame is rendered to the window, after cubos.renderer.frame and before cubos.window.render.

Dependencies

Files

diff --git a/group__scene-plugin.html b/group__scene-plugin.html index 08728dc63..5495d9626 100644 --- a/group__scene-plugin.html +++ b/group__scene-plugin.html @@ -50,8 +50,8 @@

-

Bridges

Dependencies

+

Bridges

Dependencies

Files

diff --git a/group__settings-inspector-tool-plugin.html b/group__settings-inspector-tool-plugin.html index 88d8e4019..7a89fcc72 100644 --- a/group__settings-inspector-tool-plugin.html +++ b/group__settings-inspector-tool-plugin.html @@ -51,7 +51,7 @@

-

Dependencies

+

Dependencies

Files

diff --git a/group__transform-plugin.html b/group__transform-plugin.html index 8b8ff76de..dbff5c596 100644 --- a/group__transform-plugin.html +++ b/group__transform-plugin.html @@ -50,8 +50,8 @@

-

This plugin operates on entities with a LocalToWorld component and any combination of the Position, Rotation and Scale components. For example, if you have an entity which doesn't need rotation, but has a position and a scale, you do not need to add the Rotation component, and its transform will still be updated.

Components

  • LocalToWorld - holds the local to world transform matrix.
  • Position - holds the position of an entity.
  • Rotation - holds the rotation of an entity.
  • Scale - holds the scaling of an entity.

Tags

+

This plugin operates on entities with a LocalToWorld component and any combination of the Position, Rotation and Scale components. For example, if you have an entity which doesn't need rotation, but has a position and a scale, you do not need to add the Rotation component, and its transform will still be updated.

Components

  • LocalToWorld - holds the local to world transform matrix.
  • Position - holds the position of an entity.
  • Rotation - holds the rotation of an entity.
  • Scale - holds the scaling of an entity.

Tags

Files

diff --git a/group__voxels-plugin.html b/group__voxels-plugin.html index 739eaa1bb..67079b0b5 100644 --- a/group__voxels-plugin.html +++ b/group__voxels-plugin.html @@ -50,8 +50,8 @@

-

Bridges

Dependencies

+

Bridges

Dependencies

Files

diff --git a/group__window-plugin.html b/group__window-plugin.html index 1ccb59fd5..db96a2d59 100644 --- a/group__window-plugin.html +++ b/group__window-plugin.html @@ -50,11 +50,11 @@

-

Initially sets ShouldQuit to false, and sets it to true only when the window is closed.

Settings

  • window.title - the window's title (default: CUBOS.).
  • window.width - the window's width (default: 800).
  • window.height - the window's height (default: 600).

Events

Resources

Startup tags

  • cubos.window.init - window is opened, runs after cubos.settings.

Tags

  • cubos.window.poll - the window is polled for events, sending core::io::WindowEvent's.
  • cubos.window.render - the window's back buffers are swapped.
+

Initially sets ShouldQuit to false, and sets it to true only when the window is closed.

Settings

  • window.title - the window's title (default: CUBOS.).
  • window.width - the window's width (default: 800).
  • window.height - the window's height (default: 600).

Events

Resources

Startup tags

  • cubos.window.init - window is opened, runs after cubos.settings.

Tags

  • cubos.window.poll - the window is polled for events, sending core::io::WindowEvent's.
  • cubos.window.render - the window's back buffers are swapped.

Files

diff --git a/group__world-inspector-tool-plugin.html b/group__world-inspector-tool-plugin.html index be21c6ea7..c10e5d7f2 100644 --- a/group__world-inspector-tool-plugin.html +++ b/group__world-inspector-tool-plugin.html @@ -51,7 +51,7 @@

-

Dependencies

+

Dependencies

Files

diff --git a/index.html b/index.html index 6b7daaf81..54b0f6e00 100644 --- a/index.html +++ b/index.html @@ -46,7 +46,7 @@

Introduction

-

Image

Voxel based engine

CUBOS. aims to be a simple, but powerful game engine for PC, where everything is made out of voxels.

It is open source and free to use for any purpose. Written in C++ and with data-oriented design in mind, its goal is to be both performant and highly flexible.

Getting started

The best way to get started is to read the getting started guide, which will guide you through the process of downloading and building the engine, as well as where to go from there.

There is also a feature guide which gives you a high-level overview of the engine's design and features. If you're just looking for a quick overview, this is the place to go. You can also take a look at the modules page, which describes each of the engine's modules.

In the examples page you can find examples on how to use specific parts of the engine.

If you're looking to contribute to the project, make sure you read the contribution guidelines, which introduces you to the project's conventions and code style.

Team

CUBOS. is developed by a small team at GameDev Técnico, a student group at Instituto Superior Técnico who make games. Our goal is to build a game engine from the ground up and have fun doing it.

Join us

If you're a student and interested in joining us, please fill out this form.

+

Image

Voxel based engine

CUBOS. aims to be a simple, but powerful game engine for PC, where everything is made out of voxels.

It is open source and free to use for any purpose. Written in C++ and with data-oriented design in mind, its goal is to be both performant and highly flexible.

Getting started

The best way to get started is to read the getting started guide, which will guide you through the process of downloading and building the engine, as well as where to go from there.

There is also a feature guide which gives you a high-level overview of the engine's design and features. If you're just looking for a quick overview, this is the place to go. You can also take a look at the modules page, which describes each of the engine's modules.

In the examples page you can find examples on how to use specific parts of the engine.

If you're looking to contribute to the project, make sure you read the contribution guidelines, which introduces you to the project's conventions and code style.

Team

CUBOS. is developed by a small team at GameDev Técnico, a student group at Instituto Superior Técnico who make games. Our goal is to build a game engine from the ground up and have fun doing it.

Join us

If you're a student and interested in joining us, please fill out this form.