davidcolson/polybox

Late ninties, PS1 inspired fantasy console

Polybox

Polybox is an in-development PS1 era fantasy console, a bit like Pico-8, but with simple 3D as well as 2D.

It's still rather primitive and early in development, mostly it's just a dedicated PS1 renderer right now with an old fashioned fix function pipeline. You render objects like this:

function Update(deltaTime)
    MatrixMode("Projection")
    Identity()
    Perspective(320, 240, 1, 20, 60)

    MatrixMode("View")
    Identity()
    Translate(-1.5, -1.5, -2)

    BeginObject3D("Triangles")
        Color(1.0, 0.0, 0.0, 1.0)
        Vertex(1.0, 1.0, 0.0)

        Color(0, 1, 0, 1)
        Vertex(1, 2, 0)

        Color(0, 0, 1, 1)
        Vertex(2.0, 2.0, 0.0)
    EndObject3D()
end

The above gives you the following output:

Current features

• PS1 era fixed-function 3D rendering
• Special shaders for emulating PS1 era look
• Basic flat and smooth shaded lighting
• Gltf model loading
• 2D sprite drawing
• Depth cueing fog
• Simple 2D shape drawing
• Lua VM for running your game code
• Input system that emulates a PS1 like controller

Planned features

• Luau integration
  • Picotron like buffers for handling large data
• Data serialization system
• Audio System
• Developer mode and project management system (files, config etc)
• Development tools such as level editors made in the development environment
• Some sample games
• WebGPU support
• More fleshed out 2D rendering

Supported platforms

Currently only Windows 64 bit. It shouldn't be that hard to port to other platforms though, as it uses bgfx for rendering and SDL for platform stuff. But it's early enough I have no interest in porting and testing on other platforms.

Documentation

Also too early for this, but the codebase is extremely simple and hopefully self documenting. The main API that is of interest is the GraphicsChip.h file. The entire rendering API is contained there in a very small amount of code, so small I can list it here,

void Init();
void DrawFrame(float w, float h);

// Basic draw 2D
void DrawSprite(const char* spritePath, float x, float y);

// Basic draw 3D
void BeginObject3D(EPrimitiveType type);
void EndObject3D();
void Vertex(Vec3f vec);
void Color(Vec4f col);
void TexCoord(Vec2f tex);
void Normal(Vec3f norm);

void SetClearColor(Vec3f color);

// Transforms
void MatrixMode(EMatrixMode mode);
void Perspective(f32 screenWidth, f32 screenHeight, f32 nearPlane, f32 farPlane, f32 fov);
void Translate(Vec3f translation);
void Rotate(Vec3f rotation);
void Scale(Vec3f scaling);
void Identity();

// Texturing
// Enable/Disable texturing
void BindTexture(const char* texturePath);
void UnbindTexture();

// Lighting
void NormalsMode(ENormalsMode mode);
void EnableLighting(bool enabled);
void Light(int id, Vec3f direction, Vec3f color);
void Ambient(Vec3f color);

// Depth Cueing
void EnableFog(bool enabled);
void SetFogStart(f32 start);
void SetFogEnd(f32 end);
void SetFogColor(Vec3f color);

Compiling

The project is relatively simple to compile, all you need is cmake and the MSVC build tools, and then just run the build.bat file in the root of the repo, which will run cmake and compile the project

polybox's Issues

Build Errors

I have pulled the latest commit and ran premake5.exe (vs2019).

I get build errors when running the polybox.sln.

I'm not familiar with any steps to use the code other than downloading the repository and then I guess running premake??
The instructions assume too much familiarity, I'm a complete noob so please help.

Also, I assume that to generate our own code we modify the "game.lua" file in "assets" ?

FMV playback?

Games in the PS1 loved their full motion video.

It allowed them to display bombastic action, cinematic moments or even full-scale animations alongside the models (one famous example is some of the action moments in Final Fantasy VIII)

phoboslab's pl_mpeg.h is the best single header lib for this kind of application, MPEG-1 video being very close to what the Motion Decoder in the PS1 hardware decoded blocks of. A file can also include MP2 audio thus also providing pretty much everything else needed for FMVs. The creator even outlines how to create a suitable file using FFmpeg.

I'd only look into this after all the basic features of Polybox are done, specially if you look into doing the decoding in a thread (mimicking how it works in actual hardware)

'EncodeBase64' & 'DecodeBase64' functions causes compile fail.

Both 'EncodeBase64' and 'DecodeBase64' have a return types of 'string', but attempt to return a integer in the form of NULL on lines 52 and 86, when certain conditions are met.

I know next to nothing about how this might break the engine, but as a quick fix, I set both to return NULL as a string rather than a literal.

PS1 Semi-Transparent modes?

These are quite a special feature of the PS1's GPU which tend to give even the transitions in games a really neat look, and come in 4 forms. They are implemented in emulators like Ares pretty succinctly as well. Very interesting project and I wish to keep an eye on it! :0

Cannot open include file: 'format': No such file or directory

When downloading a clean unedited version of Polybox, and attempting to build, I (maybe more people) run into a issue, multiple errors saying:
Cannot open include file: 'format': No such file or directory
which is preventing me from building. Is this a issue on my end, or a already known issue? And what is a solution/workaround?

EDIT: Is there a include dependency or something different needed? I have saw fmt/<file>.h in multiple files, is fmtlib missing? And if so, how to correctly include it?

Approachability & Compiled Exe

This is a great idea for a fantasy console! However, one of the things that made Pico8 so great was that you just download it and you jump right in even with little knowledge. You open it up and have access to easy editing textures, music, code all right there in the same program. That was great for getting over the initial learning curve.
Granted 3D development is a lot trickier ,but I think at least you could provide a streamlined interface like that. As it stands you don't even offer the compiled exe, when that is standard for most Windows projects on Github.
I think you could start by offering an exe, as well as example programs, and have them up front on the github. Otherwise, you risk scaring off new users.

Building

Hi, I'm trying to build the project on Linux (not sure if that's possible).
I'm getting this:

$ lua premake5.lua                                                                                                                    
lua: premake5.lua:2: attempt to index a nil value (global 'path')
stack traceback:
        premake5.lua:2: in main chunk
        [C]: in ?

I don't know the first thing about lua, and I tried both 5.1 and 5.4. I tried googling this message but most answers point to a scoping problem specific to the script, not missing dependencies (might be wrong though).

Would you know what needs to be installed and how to build the project on Linux?