DOCSEARCHbyAlgolia
Submit Docs

Pyrite64

repository·main·Indexed 25 days ago

https://github.com/hailtododongo/pyrite64

A toolset for N64 development featuring the tiny3d 3D engine and fast64 material authoring tools. It provides a specialized editor and pipeline to work within the N64 hardware's fixed-function pipeline constraints, supporting GLTF (.glb) model imports, PNG texture conversion to N64 runtime formats, and bone-based animations.

Tokens
27.5K
Snippets
36
Records
200
Agent score
84%

What's inside pyrite64

  1. Understand Pyrite64 Scene Structure

    main

    Pyrite64 uses a scene-based structure to manage game logic and data. A scene acts as a self-contained container that defines a set of objects, their behaviors, and general game settings.

    Key lifecycle behaviors:

    • Loading a scene: All objects defined in the scene are spawned, and game logic is handled by their components.
    • Unloading a scene: All objects are removed from the game, and the next scene is loaded.
    • Isolation: Each scene starts from nothing and returns to nothing when finished, allowing for different game types (e.g., menus vs. levels) to coexist in the same project.

  2. Understand the Pyrite64 architecture

    main

    Pyrite64 is divided into three distinct parts:

    1. Engine: Code that executes on the N64 console. It utilizes Libdragon (for kernel, 2D graphics, audio, input, and filesystem) and tiny3d (for 3D graphics, models, and animation). Pyrite64's engine code implements scene-based logic, including asset management and object behavior.
    2. Editor: A PC-based program used to visually create and setup scenes. It includes the visual editor, the build system, and the CLI. The editor stores data as pretty-printed JSON files, which are converted into optimized binary assets during the build process.
    3. Project: The actual game being developed, consisting of assets, scripts, and scene data.

  3. Implement non-physical movement with Character Body

    main

    The Character Body is a specialized helper for implementing movement for objects that require manual control over collision resolution (e.g., players or enemies). It handles gravity, collision sweeps, wall sliding, stair stepping, and floor snapping.

    Unlike standard colliders, a character body is an observer: it will not be moved by forces from other colliders and is invisible to rigid-bodies. To move the character, you must set an input velocity and call moveAndSlide() each frame.

  4. Understand the Pyrite64 Material System

    main

    In Pyrite64, materials represent the draw settings used by 3D models, such as colors and textures.

    By default, 3D models imported into the engine contain material information from fast64, which Pyrite64 uses as the default state. You can modify these materials using the Pyrite64 Editor or via the runtime C++ API.

  5. Understand the Pyrite64 Material System

    main

    Pyrite64 manages N64 hardware state (textures, color registers, blending, anti-aliasing) through a hierarchical material system. This system abstracts the process of sending commands to the RSP and RDP processors to ensure settings are applied correctly during draw calls.

    Settings are applied at different stages of the hierarchy:

    • Frame level: Settings set once per frame.
    • Layer/Model level: Settings applied per draw-layer or per 3D-model.
    • Object/Component level: Settings applied per individual object via the Material System.

    To allow for dynamic changes (like changing the color of a specific object without affecting others), the system uses a distinction between Materials and Material Instances.

  6. Run the Pyrite64 Editor

    main

    Once built, you can execute the editor using ./pyrite64 (Linux/macOS) or .\pyrite64.exe (Windows).

    Important: While the executable can be moved anywhere on your system, the ./data and ./n64 directories must remain in the same directory as the executable for it to function correctly.

    ./pyrite64

  8. Manage Pyrite64 project directory structure

    main

    A Pyrite64 project follows a specific directory structure. You should place your assets and custom code in the designated folders:

    • assets/: Place textures, models, and audio files here. Sub-directories are allowed. These are converted to optimized binary files at build time.
    • data/: Contains editor-generated JSON files. Do not modify these files manually.
    • src/user/: Place your custom C++ code here. Any .cpp files in this directory (including nested sub-directories) are automatically picked up and compiled. Scripts created in the editor are also placed here.
    • src/p64/: Contains editor-generated source code. Do not modify these files.
    • project.p64proj: The project definition file.
    • .gitignore: Automatically generated to ignore build artifacts.
    Project/
├── assets/
├── data/
│   └── scenes/
│       └── (individual scenes)
├── src/
│   └── p64/
│   └── user/
├── .gitignore
└── project.p64proj

  9. Understand and add Components to objects

    main

    Components are the fundamental building blocks attached to objects in Pyrite64 to provide specific behaviors. An object can possess multiple components, and all attached components are evaluated together during every frame.

    To add a component to an object, use the "Add Component" button located within the object inspector in the editor.

  11. Configure Colliders and Rigidbodies (v0.7.0)

    main

    The physics system was split into Colliders (for detection) and RigidBody components (for simulation/response).

    • Colliders: The isFixed flag was removed. Colliders now support more shapes (Sphere, Box, Capsule, Cylinder, Cone, Pyramid) and can be arbitrarily oriented. They also expose friction and bounce settings.
    • Rigidbodies: Use the RigidBody component for physical simulation. Objects without a RigidBody will only trigger collision events but will not be simulated or separated on collision.
    • Migration: To access simulation, replace Comp::CollBody with Comp::RigidBody. To access specific collider properties, continue using Comp::CollBody (or the collider component).

  12. Use the Editor Menu Bar

    main

    The top menu bar provides access to global project and editor actions:

    • Project: Manage saving, closing, or opening the Project Settings dialog.
    • Edit: Perform Undo/Redo actions or access Preferences (shortcut: Ctrl+.).
    • Build: Trigger Build, Build & Run, or Clean operations.
    • View: Manage viewports, UI scaling (Zoom), Themes, or Reset Layout.

    Quick Run: Use the green play button on the far right of the menu bar or press F12 to build and run the game.