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.

For anything 3D, 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:

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:

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.