General Structure
====================================

| As many similar game-engines, the general structure is split into distinct parts.
| In this case: the engine, the editor, and the project itself.

Engine
----------------

| The **Engine** refers to any code that will execute on the N64 console.
| This contains Libdragon, tiny3d and Pyrite64's runtime logic.

| N64 programs in itself run on bare-metal, meaning there is no OS sitting on the console.
| Instead, a basic bootloader and OS/kernel is provided by an SDK,
| and then compiled into the game.

| Luckily all of that is handled by Libdragon, even offering a lot of additional APIs.
| Besides a kernel, this also includes things like 2D graphics, audio, input, and a filesystem.
| You can find a feature list here if you want to know more: `libdragon.dev <https://libdragon.dev>`__.

| For anything 3D, `tiny3d <https://github.com/HailToDodongo/tiny3d/>`__ is used.
| This is a more low-level ucode and library, focusing on performance and an easy API.
| However it also comes with a builtin model format, animation system, and higher-level APIs.

| Lastly, Pyrite64's engine code implements a scene-based game logic using both libraries.
| This means things like asset-management, scenes and objects, rendering, and dealing with behaviour of objects is done through it.

| So unlike a library-based workflow, you don't need to implement anything for the engine itself.
| Instead only the logic for objects and assets needs to be created, the rest can be plugged together in the editor.

Editor
----------------
| **Editor** refers to the program you run on your PC to create games.
| This does not just include the visual editor, but also parts of the build system and the CLI.

| Its job is to let you create and setup scenes in your game in a visual way.
| All of the data it handles is stored as pretty-printed JSON files,
| which fully define your game/scene setup.

| During build, those are then converted into optimized binary assets for runtime-use.
| The engine part will then load and use those binary files to setup the scene at runtime.

| Those are just internal details however, all of the building and loading is handled automatically.

Project
----------------
| Finally we got the **Project** itself, which is the game you are making.
| This is a directory containing all of your assets and scripts, as well as the scene data the editor creates.
| The structure of it is defined and created by Pyrite64, which looks like this:

.. code-block:: none

  Project/
  ├── assets/
  ├── data/
  │   └── scenes/
  │       └── (individual scenes)
  ├── src/
  │   └── p64/
  │   └── user/
  ├── .gitignore
  └── project.p64proj

Meaning of each directory
^^^^^^^^^

| ``assets`` contains things like textures, models, and audio files.
| Those are later build into optimized binary files for runtime use.
| The editor usually also offers settings for things like compression or formats.
| This is the place to put your own game assets in, sub-directories are also allowed.

| ``data`` contains all of the data created by the editor.
| You should not manually touch any of these files.

| ``src`` is where source code specific to your project goes.
| The ``src/p64`` contents should not be modified, as it contains generated sources by the editor.
| ``src/user`` is where any custom code can be put.
| Everytime your create a C++ script in the editor, it will be placed there.
| However, you can also place completely custom C++ there,
| all .cpp files are automatically picked up (even nested in sub-dirs) and compiled into the game.

Temporary build files
^^^^^^^^^

After a first build, you will also see additional files:

.. code-block:: none

  Project/
  ├── build/
  ├── engine/
  ├── filesystem/
  ├── Makefile
  └── *.z64

| Those should never be modified, and are only build / cache files.
| Meaning they are purely derived form the above source files.
| However to still explain what they are:

| ``build`` contains compiled C++ sources.
| ``engine`` is a local copy of the Pyrite64 engine, it gets auto-updated when needed.
| ``filesystem`` contains the runtime filesystem with optimized binary assets.
| The ``Makefile`` is used to build the game, and fully generated by the editor.
| The ``.z64`` file is the final ROM, the only file out of these you will have to interact with.

Version Control
^^^^^^^^^

| It is highly recommended to use version control for your project!
| Sooner or later you **will** lose work otherwise by accident.

| By default a ``.gitignore`` file is created for you, which ignores all of the above build files.
| So you can just initialize a git repo and commit all visible files.

| Since a project is self-contained, checking out that committed state on another PC
| allows you to then fully build it there too.

| While extremely unlikely, a potential corruption of project files themselves,
| can then also be solved by just rolling back to a previous commit.

| If you face any merge conflicts, resolving should be possible in most cases,
| as the editor files under ``data`` are pretty-printed JSON files for that reason.

.. _Libdragon_ :