Install Requirements

You will need the following libraries and applications installed, in the future the library will search for these requirements by itself and install them:

• Haskell Toolchain (ghc, stack, cabal), ghcup is a convenient solution: https://www.haskell.org/ghcup/
• sdl (window management), Ubuntu: run sudo apt install libsdl2-2.0-0; Windows: Run this command in your Haskell MinGW application: pacman -S mingw-w64-x86_64-SDL2
• glfw (low level window functions), available here: https://www.glfw.org/
• libpq (to support Realm/DB functions), available here: https://www.enterprisedb.com/downloads/postgres-postgresql-downloads
• NEW! ruby (to use the ScriptEngine Module), on linux you need to install ruby where pkg-config can find it, for windows you will need https://rubyinstaller.org/. Then follow these extra steps:
  • Modify hruby.cabal so it's extra-lib-dirs is an absolute path to lib in the project root folder on your machine
  • OPTIONAL: If the provided .dlls have issues then replace x64-ucrt-ruby320.dll and x64-ucrt-ruby320.dll.a with provided versions from rubyinstaller.

WRayLib3d Module/Engine Structure (Unity-Like FP Application)

Frontend

• monomer

Application/Library

• Core
• GameEngine
• Network
• ScriptEngine
• GuideWriter
• Utils

Low Level Backends

• gl
• directx
• metal
• vulkan
• sdl2/glfw
• protea-audio

Engine Structure In-Depth

• Core (Module)

  • Build Manager Handles the Building of Projects (WRLP) Into full native executables at the high level (planned support: Win32/64 (NSIS Executable), UWP, MacOS, iOS*, Linux
    Application, Android*, Wasm, XR*), It may need** a companion Launcer Manager.

    • = iOS Support is theoretical whereas Android is possible but would require generating an Android Studio Project, this is a similar issue currently facing the UWP functionality which similarly has to convert this project into a functioning VS Solution/Project

      Djinni (https://github.com/MilesLitteral/djinni) may be an interesting tool to help with translating code for making iOS and Android Project I will have to explore what is to be done for VS and XC though I am sure they have, atleast, means of generation through Command-Line, the question is then linking

    ** = besides a Launcher it may also need a Cross Compiler (Xross is the working title)

  • Xross a "Cross Compiler" full of low level functions and templates for generating the appropriate code to run the game on the applicable platform when building, it is designed to be used in conjunction with the native build environment. Xross is more like a set of tools the engine contains that are especially for condoning build function; in this sense Xross is not really a Compiler so much as it is:

    • template scripts for creating CMake, Make(via AutoMake), or WebGL Projects
    • an interface class (hs2c.cpp) which runs hs_init and allows c++ to boot the Engine rather than a haskell script
    • ghc-wasm-meta for generating WebAssembly code from haskell scripts
    • ghc-js for generating JavaScript from Haskell
    • djinni for generating C++ code that can then be compiled to Objective-C or Java, critical for mobile development support.

    In general Xross uses CMake to generate vsprojs or xcprojs (On Windows and Mac) while ghc/gcc handles the building of any shared libraries when applicable. AutoMake to generate the necessary files to run ./configure, make, and make install on linux.

    The user may sidestep make/cmake and simply mark the executable generated by ghc for compilation to an NSIS executable which simply bundles what GHC builds and Xross would not be used in this case, only the build manager and ghc would be (ghc can build exes on all platforms)

    Xross is imperative to building for Web or Mobile as it's functions are required for turning the Haskell Code into something applicable to web/mobile (where Haskell is not applicable, only it's c code or dlls would be)

    Xross would be used when generating C++ interfaces for all necessary code on mobile which can also use hs_init to run wraylib3d. haskell and mobile is a new frontier and how well the engine works on mobile is yet to be seen (elaborate C++ interfaces may exist in the future in general that can be allow for hs<->c++ communication)

    Xross would also utilize hs2c which is imperative to getting the engine to work in vscode or other system contexts.

    It's possible to beef this portion up so it can access package managers and build tools for better linking, Xross will contain Linking module in the future for making sure AssetBundles and ShaderCaches aren't lost and the appropriate libraries (like wrl3d.dll or wrl3d.exe ) aren't lost in the build process

    In the future Xross may also help condone the creation of React(JSX) projects as a potential export option

  • Resource Bundler Handles The compiling of all project 3d Assets (and associated assets) into .AssetBundles which are accessed at runtime. AssetBundles can be thought of like onion data structure, ie: AssetBundle ([(Key, GLB(Header, [GLTF]))])

    Currently, The engine handles this with .PK3 files that bundle everything, they are basically glorified zips and there is an active desire to eliminate them from the code base. By comparison maps are represented by Binary Space Partitions (BSPs) and will remain their format but be stored within a MegaStore. It is recognized that BSPs could be turned into GLBs or GLTFs into themselves. Audio could even be stored in the gltfs with the KHR_Audio extension but this needs to be explored.

  • Structured Data Descriptions of All ingame classes as JSON, XML, or YAML data structures, these are then used for serialzing the game as save files or transmittable data.

  • Shader Precompiler Pipeline Handles packaging of applicable Shaders to ShaderCaches (MegaStores) which are accessed at runtime this system is part of an ongoing process to completely deprecate the use of Quake3 Shaders and move to a modern shader system (SPIR-V support in gl backend, done as of 5/8/23).

    These caches will be used by the renderer cross-referenced against .gltf file specific 'extensions' which would then load the applicable shader if this is not present the cache has a "default shader" that will be fallen back to

    This module also contains the language-glsl, and language-metal parsers used to validate all shaders

    Currently the engine uses "LC" a kind of custom shader scripting language that largely is used in relation to Engine Graphics. I desire to replace this as some point with GLSL and SPIR-V support, which can be used rather than emulating to make Quake happy. LC is an associated language of LambdaCube, the renderer this application is built ontop and forks it's own build of.

  • Window System Handles SDL2 Windowing and User Interface Creation at Application level At some point, it will have a full Front-End Interface to create Widgets in Window with scriptable UIs. Currently Monomer is being used to implement the front-end UI, a fork of it is available in the submodules folder with extensive modifications in the interest of building a 3d application rather than just a 2d one with the author's blessing (not to say he endorses this library, WRaylib3d, in any way shape or form)

    WRayLib uses Protea Audio and therefore can use OGGs and WAVs, there is an interest in maybe making an Audio System to go along with it built on top of SDL2.

    When this exists fully, SDL2 will handle Input (Controllers), Audio, Windowing, and Widgets therefore separating concerns in terms of which modules handle what, its currently a bit of a mess

• Game Engine (Module)

  • Data Contains all Type Level descriptions of ingame data like Maps (BSP), GameCharacters, Models (MD3) There is an ongoing effort to add new Bits such as GLBs and GLTFs

  • Graphics Contains Functions for operating on the Data Types and Rendering them, currently the Rendering Pipeling presumes that everything will be interms of OpenGL Buffers, efforts are thus focused on having the GLBs read into lists of GLTFs then the GLTFs are loaded and read into OpenGL Buffers, at a later point in Development the Rendering Pipeline will be backend agnostic and the Buffers will instead be a kind of Intermediate Representation (IR), expanding on LambdaCube-IR and probably LambdaCube-Compiler

    There was a time that I entertained creating a LambdaCube-DX for DirectX but I instead decided Vulkan would maximize platform support and save time, additionally, Vulkan can use native D311 and D312.dll where as it CANNOT do native Metal rendering (it can only communicate with metal-api which creates a bottleneck in Vulkan) thus LambdaCube-Metal is somewhat necessitated by comparison Related Projects: LambdaCube-Vulkan, LambdaCube-Metal, LambdaCube-XR, LambdaCube-GL (The Backends) (all will be renamed to eclipse-x)

    lambdacube will be renamed to eclipse in the interest of this, lambdacube-gl should be replaced with eclipse-gles whic has to be written

    There's also a desire to upgrade LambdaCube-IR to use GraphQL as a querying language rather than JSON as it's currently using this is because GraphQL is incredibly flexible, and will need to be explored

  • Loader Contains functions for reading the Binary File Types into their Logical Data Types, a GLB and GLTF Loader is in Progress.

  • MapViewer Module for Loading Levels and viewing them, Full of QoL TODOs that will be addressed later on in development.

    There is a desire to create a MapMaker, I'm not saying this should be Blender-HS but I am interested in Map Making functionality similar to Unity/Unreal Engine.

  • Realm Module for Games and their Definition, here game logic, entities, levels, physics, and all are defined This class is what users build via the UI and is actually "Compiled" by WRL3D when the user exports their game, rather, the assets here and logic here is what will be compiled as an executable with dlls, assetBundles, and binaries. There is an interest here to add the DB Module connections, and a module for reading a companion .db file.

  • All Other files in here relate to core Game Engine functions, Render System, Scene (Manager), and Utils will stay whereas there is a desire to work Collision and Content into their own Modules (Physics, and Content respectively).

• Network

  • Database Low level Postgres-SQL Functions, so far it only contains Query, which is all that is necessary for Realm purposes; you are required to have PostgresSQL installed on your system to use pgl if you want to use this module and it is bound to pgl otherwise this module creates segfaults.

  • Requests Low Level HTTP Functions, it can query web addressed in terms of HTTPS, JSON, or Binary and can handle all those responses, in the future any UDP Streaming functions will be described here for Multiplayer functionality as will any SSH or Tunneling functions that are of future interest

  • Realms Levels as described in their Web format, Levels can be queried and their assets downloaded. This Module will probably be more important when Multiplayer is a thing in the future

  • Cloud A Module which handles interfacing with a SaaS like Firebase or Supabase if the User Desires, look here for all analytic needs

• Script Engine

  • All Definitions for HRuby, later will be a generalized interface that the user can use to script ingame actions , mods, and logic. Planned support: Python(https://hackage.haskell.org/package/hpython), Ruby(https://hackage.haskell.org/package/hruby), custom build included that builds to Ruby 3.2 rather than 2.2), and Lua(https://hackage.haskell.org/package/hslua)

• Benchmarks

  • Application Benchmark Utilities, it has a Benchmark for running the mapviewer, running the default game, and entries for custom benchmarking full games or individual functions

  ? There is a desire to make visualization functions so that benchmarking can be presented Graphically or non Graphically

• GuideWriter

  • A Module for Generating LaTeX PDFs via HaTeX (haskell latex)
  • This will be a general utility that could evolve into other notation forms for UI etc

• Utils

  • Misc Application Utils, all Logging functions for example are here, as is prettyPrinting and Md3Show; the PrettyPrinter is entirely broken and needs to be fixed for generalized use. There needs to be an added GlTFShow, and GLBShow utility (perhaps it could be called ModelViewer), there is also the small need for a MegaStore Printer, ConfigShow, and a tracer (stack trace?)

Config.Yaml

Will be expanded to include Tests, examples, and alternative builds based on simple flags passed as well as flags for conditions like if sdl2 is not installed leaving only the need to install libpq.

Stack.Yaml

Used to control which extra modules are being built like which lambdacude backend the Application will build with (currently it only builds with lc-gl) in the future available rendering backends will be:

• opengl (legacy)
• opengl-es (gles)
• metal (apple only, optional for apple users)
• directx (Windows Only, optional for Win64 users)

Window rendering backends available will be:

• vulkan (default, includes xr and metal-api support)
• sdl2/glfw (software renderer)

How To Run WRayLib3d

System Prerequisites: ghc, stack, cabal (ghcup toolchain), opengl Core Dependencies: lambdacube-compiler, lambdacube-ir, lambdacube-gl (There is no need to satisfy optionals, and they all come in the project anyway, enable and disable them with the config.yaml)

in shell: stack build then stack run

How To Run The MapViewer or Demo

If it is not already present in root then you must first download this .pk3 (In the future it will be replaced by an "AssetBundle" (MegaStore): https://github.com/patdohere/dockerfiles/raw/master/quakejs-stack/quakejs/base/baseq3/pak0.pk3

Place "pak0.pk3" in the root directory (./WRaylib3d) in shell: stack run mapviewer-debug

Notes:

• lambdacube-metal requires now requires metal-cpp(https://developer.apple.com/metal/cpp/files/metal-cpp_macOS14.2_iOS17.2.zip), mtlpp(https://github.com/MilesLitteral/mtlpp) has been deprecated in favor of it.
• Note if you wish to test the WebAssembly module you will need wasmtime installed on your machine: https://wasmtime.dev/. WASM support is extremely limited at the moment.

Will WRayLib3d have companion apps?

Yes, they will be written with the fjvallarino/monomer library exclusively, one that could be made now is the Multiplayer launcher, the rest are TBA,

How would exported games look in terms of exported filesystems?*

General FS:
C:/WRL/Projects/<YourGame>
  AssetBundles/assets.AssetBundle(s)
  ShaderCaches/shader.ShaderCache(s)
  src/game/.hs(')
  src/gameScripting/.rb(s)
  Realms.db
  YourGame.wrlp

Windows:
NSIS (Standard)
C:/WRL/Games/<YourGame>
  AssetBundles/assets.AssetBundle(s)
  ShaderCaches/shader.ShaderCache(s)
  WRL3D.dll
  Realms.db
  YourGame.exe

UWP
C:/WRL/Games/<YourGame>
  <vcproj files>
  WRL3D.dll
  YourGame.vcproj -> ./build/YourGame.uwp

MacOS:
/user/WRL/Games/<YourGame>
  AssetBundles/assets.AssetBundle(s)
  ShaderCaches/shader.metallib(s), shader.metaldysm(s)
  WRL3D.so
  Realms.db
  <xcproj/xcworkspace files>
  YourGame.xcproj -> ./build/YourGame.app

Linux
/user/WRL/Games/<YourGame>
  AssetBundles/assets.AssetBundle(s)
  ShaderCaches/shader.ShaderCache(s)
  configure
  Makefile 
  WRL3D.so
  autogen.sh
  Realms.db
  YourGame.o

wasm
ftp://127.0.0.1/YourGame/
  -- (Data URI)  AssetBundle(s)
  -- (Data URI)  ShaderCache(s)
  -- (DB Tunnel) Realm(s)
  WRL3D.so/dll
  YourGame.wasm

WebGL (TBA via ghc-js, See Also: https://webglfundamentals.org/webgl/lessons/webgl-boilerplate.html)
 ftp://127.0.0.1/YourGame/
 -- (Data URI)  AssetBundle(s)
 -- (Data URI)  ShaderCache(s)
 -- (DB Tunnel) Realm(s)
 Build
 TemplateData
 index.html
 
iOS
/user/WRL/Games/Mobile/<YourGame>
  AssetBundles/assets.AssetBundle(s)
  ShaderCaches/shader.metallib(s), shader.metaldysm(s)
  Realms.db
  <vcproj/xcworkspace files>
  YourGame.xcproj -> ./build/YourGame.ipa (iOS)          
  
Android
../user/WRL/Games/Mobile/<YourGame>
  AssetBundles/assets.HSAssetBundle(s)
  ShaderCaches/shader.ShaderCache(s)
  app/
  build/
  gradle/
  <gradle_files>
  Realms.db
  settings.localproperties
  build.gradle -> ./build/YourGame.apk

XR Headsets
../user/WRL/Games/Mobile/<YourGame>
  -- (Data URI)  AssetBundle(s)
  -- (Data URI)  ShaderCache(s)
  -- (DB Tunnel) Realm(s)
  app/
  build/
  gradle/
  <gradle_files>
  settings.localproperties
  build.gradle -> ./build/YourGame.apk
OR JUST `./<YourGame>/YourGame.uwp` + .dlls

• = There is a desire for CMake support, this has to be explored as it could also be the answer for generating vcprojs and xcprojs. as well as AutoMake support for linux. There is an interest in !xmake