From a0362e7717bd7343bbaf360cb8a4b24a91fa97a7 Mon Sep 17 00:00:00 2001 From: Ricardo Antunes Date: Sat, 9 Mar 2024 16:48:11 +0000 Subject: [PATCH] docs: add exercises page --- docs/pages/2_features/main.md | 5 +- docs/pages/4_exercises/main.md | 60 +++++++++++++++++++ .../main.md | 0 docs/pages/main.md | 3 + 4 files changed, 65 insertions(+), 3 deletions(-) create mode 100644 docs/pages/4_exercises/main.md rename docs/pages/{4_contribution => 5_contribution}/main.md (100%) diff --git a/docs/pages/2_features/main.md b/docs/pages/2_features/main.md index fce30f43e4..000ec95e31 100644 --- a/docs/pages/2_features/main.md +++ b/docs/pages/2_features/main.md @@ -44,9 +44,8 @@ dive into the documentation of each class and function. ## What we don't have and where are we going The engine is still in its early stages of development, and thus we're missing -a lot of features. For example, we don't have physics yet, and the editor tools -are very barebones - you can't even load a scene from a file yet. There's no -scripting language, thus you will have to write all your game logic in C++. +a lot of features. For example, we don't have rigid body physics yet, and the editor tools are very bare bones. +There's no scripting language, thus you will have to write all your game logic in C++. Making a game with the engine is still very painful. Our goal is to make **CUBOS.** usable for game jams by people who are not on the team. This means a diff --git a/docs/pages/4_exercises/main.md b/docs/pages/4_exercises/main.md new file mode 100644 index 0000000000..d03c46a5d7 --- /dev/null +++ b/docs/pages/4_exercises/main.md @@ -0,0 +1,60 @@ +# Exercises {#exercises} + +This page contains challenges designed to help you start working with **CUBOS**. +We recommend that you start by reading the @ref getting-started "getting started" and @ref features "features" guides. + +## Creating a new engine sample + +Before moving on to the actual exercises, lets start by creating your own empty sample, which will be expanded upon the next steps. + +Start by creating a new folder in the `engine/samples` directory, i.e., `engine/samples/my-own-sample`. +Make sure to add a `main.cpp` to that folder, with the following base code: + +```cpp +#include + +using namespace cubos::engine; + +int main() +{ + Cubos cubos{}; + cubos.run(); +} +``` + +The final step is to add your new sample to the CMake configuration, at `engine/samples/CMakeLists.txt`. +Open that file, and add a new line of the form `make_sample(DIR "my-own-sample" ASSETS)`. + +If you now reconfigure CMake, you should be able to launch the target `engine-sample.my-own-sample`. +Don't worry if nothing shows up yet - in **CUBOS** you only get what you ask for, and in the code above we didn't do anything except run an empty application. + +## Showing a cube + +Try making your sample open a window and show a simple voxel cube! To do this, you will need to: +1. Add the @ref renderer-plugin "Renderer plugin". +2. Create a @ref cubos::engine::VoxelPalette "VoxelPalette". +3. Create a @ref cubos::engine::VoxelGrid "VoxelGrid". +4. Create a @ref cubos::engine::PointLight "PointLight". +5. Create a @ref cubos::engine::Camera "Camera" and add it to @ref cubos::engine::ActiveCameras "ActiveCameras". + +You can take inspiration from the @ref examples-engine-hello-cubos "Hello CUBOS" @ref examples-engine-renderer "Renderer" samples. + +## Replace the cube by an actual voxel model + +Of course we don't expect developers to generate their voxel models through code! +Change your sample to show an actual voxel model, created and stored in a `.qb` file. +You can create one using [MagicaVoxel](https://ephtracy.github.io/), or simply download an existing model from the internet. + +**CUBOS** doesn't handle `.qb` files directly: it only supports `.grd`'s and `.pal`'s, our own formats for voxel grids and palettes. +You can use **QUADRADOS** to convert a `.qb` to a `.grd` and `.pal`. Check out its @ref features-quadrados "feature guide" for more information. + +Take a look at the @ref examples-engine-voxels "Voxels" sample to figure out how you can load those files into the actual sample. + +## Move the voxel model on input + +Make the model you added previously move when some buttons are pressed. You will need to: +1. Add the @ref input-plugin "Input plugin". +2. Create an input bindings asset. +3. Add a system which uses the @ref cubos::engine::Input "Input" resource to move the model. + +Check out the @ref examples-engine-input "Input" sample for inspiration. diff --git a/docs/pages/4_contribution/main.md b/docs/pages/5_contribution/main.md similarity index 100% rename from docs/pages/4_contribution/main.md rename to docs/pages/5_contribution/main.md diff --git a/docs/pages/main.md b/docs/pages/main.md index b63e61d141..fccdc80647 100644 --- a/docs/pages/main.md +++ b/docs/pages/main.md @@ -25,6 +25,9 @@ quick overview, this is the place to go. You can also take a look at the In the @ref examples "examples page" you can find examples on how to use specific parts of the engine. +Consider taking a look at the @ref exercises "exercises page" if you want some +challenges to help you understand how to work with **CUBOS**. + If you're looking to contribute to the project, make sure you read the @ref contribution "contribution guidelines", which introduces you to the project's conventions and code style.