diff --git a/README.md b/README.md index 91c2930bd..cda05813f 100644 --- a/README.md +++ b/README.md @@ -7,9 +7,10 @@ ![Metaforce screenshot](assets/metaforce-screen1.png) + ### Download -This project is currently in **Alpha** state, so expect bugs. -Builds available at [https://releases.axiodl.com](https://releases.axiodl.com). +This project is currently in **alpha** state. +Builds are currently unavailable while the project undergoes large changes. ### Platform Support * Windows 10 (64-bit, D3D11 / Vulkan) @@ -17,10 +18,10 @@ Builds available at [https://releases.axiodl.com](https://releases.axiodl.com). * Linux (Vulkan) * Follow [this guide](https://github.com/lutris/docs/blob/master/InstallingDrivers.md) to set up Vulkan & appropriate drivers for your distro. -### Usage (GUI) +### Usage Windows: -- Open `metaforce-gui.exe` +- Open `metaforce.exe` macOS: - Open `Metaforce.app` @@ -29,26 +30,7 @@ Linux: - Ensure AppImage is marked as executable: `chmod +x Metaforce-*.AppImage` - Open `Metaforce-*.AppImage` -### CLI usage (GC versions) - -* Extract ISO: `hecl extract [path].iso -o mp1` - * `mp1` can be substituted with the directory name of your choice -* Repackage game for Metaforce: `cd mp1; hecl package` -* Run Metaforce: `metaforce mp1/out` - -### CLI usage (Wii versions) - -**IMPORTANT**: Trilogy main menu currently doesn't work, and requires the `--warp 1 0` command line arguments to get in-game. - -NFS files dumped from Metroid Prime Trilogy on Wii U VC can be used directly without converting to ISO. - -* Extract ISO or NFS: `hecl extract [path].[iso/nfs] -o mpt` - * `mpt` can be substituted with the directory name of your choice -* Repackage game for Metaforce: `cd mpt; hecl package MP1` - * The `MP1` parameter is important here. -* Run Metaforce: `metaforce mpt/out --warp 1 0` - -#### Metaforce options (non-exhaustive) +#### CLI options (non-exhaustive) * `-l`: Enable console logging * `--warp [worldid] [areaid]`: Warp to a specific world/area. Example: `--warp 2 2` @@ -75,16 +57,15 @@ NFS files dumped from Metroid Prime Trilogy on Wii U VC can be used directly wit build-essential curl git ninja-build clang lld zlib1g-dev libcurl4-openssl-dev \ libglu1-mesa-dev libdbus-1-dev libvulkan-dev libxi-dev libxrandr-dev libasound2-dev libpulse-dev \ libudev-dev libpng-dev libncurses5-dev cmake libx11-xcb-dev python3 python-is-python3 \ - qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools libclang-dev libfreetype-dev + libclang-dev libfreetype-dev libxinerama-dev libxcursor-dev python3-markupsafe libgtk-3-dev ``` * Arch Linux packages ``` - base-devel cmake ninja llvm vulkan-headers python3 qt6 clang lld alsa-lib libpulse libxrandr freetype2 + base-devel cmake ninja llvm vulkan-headers python python-markupsafe clang lld alsa-lib libpulse libxrandr freetype2 ``` * Fedora packages ``` - cmake vulkan-headers ninja-build clang-devel llvm-devel libpng-devel qt6-qtbase-devel - qt6-linguist qt6-qttools-devel qt6-qtscxml-devel qt6-qtsvg-devel qt6-qt5compat-devel + cmake vulkan-headers ninja-build clang-devel llvm-devel libpng-devel ``` * It's also important that you install the developer tools and libraries ``` @@ -151,21 +132,3 @@ cmake -G Xcode ../metaforce ``` Then open `metaforce.xcodeproj` - -#### Optional Debug Models -We provide custom debug models for use to visualize certain aspects of the game such as lighting, in order to use -these models you may download them from https://axiodl.com/files/debug_models.zip and extract to `MP1/URDE` in an -existing HECL project (assuming paths are relative), then run the following command: - -```sh -hecl package MP1/URDE -``` -This will cook and package the debug models and will automatically enable rendering of lights in a debug build of Metaforce. - -### Blender Known Issues -On Windows it is known that paths >240 characters will cause blender to fail while attempting to open/create a file, causing hecl to stall. -We currently do not have a good fix for this issue, however a workaround is to place hecl near the root of your directory tree -and executing from there e.g: -`D:\HECLProjects\` -Another work around is to install a version of python that matches the one blender ships with and renaming the python directory in the blender directory to `python.bak`. -This will force blender to use the system's python if it's available and will not have the same path limitation diff --git a/README.msan.md b/README.msan.md deleted file mode 100644 index 60bce969c..000000000 --- a/README.msan.md +++ /dev/null @@ -1,57 +0,0 @@ -## Instrumenting URDE with MemorySanitizer - -*For Linux and OpenGL only.* - -To enable checking for uninitialized memory accesses with -[MemorySanitizer](https://clang.llvm.org/docs/MemorySanitizer.html), pass -`-DURDE_MSAN=On` to the CMake command line. -URDE and boo will conditionally disable certain features when MemorySanitizer -is enabled. Audio will not be processed in order to avoid the significant -CPU expense required for mixing. Disabling audio also avoids the need to -track allocations made by PulseAudio. Additionally, DBus functionality is -disabled to avoid tracking its allocations. - -MemorySanitizer ideally requires all code in the process be compiled for -instrumentation. In practice this is not easy since several system and -multimedia libraries are dynamically linked by URDE. -Two key system additions/modifications are required to successfully instrument. - -### libc++ - -The C++ runtime has numerous instances of memory allocation. The easiest way -to ensure these are instrumented is to build libc++ and libc++abi with -MemorySanitizer enabled. Follow -[these instructions](https://github.com/google/sanitizers/wiki/MemorySanitizerBootstrappingClang) -up to the "Build libc++ and libc++abi with MemorySanitizer" step. -Once built, install them onto your system. - -### Mesa - -*Tested with Radeon SI only. Might work with Intel and Nouveau as well.* - -There is not much to do with URDE in the absence of a graphics acceleration -library. Unfortunately, Mesa is a beast of a library that does not handle -MemorySanitizer instrumentation well. As an alternative, boo uses MSan's -API to contextually disable memory tracking when frequently-used OpenGL -functions are called. - -Unfortunately, the Radeon SI driver (and probably others) spin up a work -queue thread that URDE has no visibility of. Memory allocations in this -thread will generate an unmanageable quantity of reports. Mesa has a convenient -thread entry implementing a generic work queue for drivers to make use of. - -`#include ` and add the following code to the beginning of -`util_queue_thread_func` in `src/util/u_queue.c`: -```cpp -typedef void (*msan_function)(void); -msan_function func = dlsym(RTLD_NEXT, "__msan_scoped_disable_interceptor_checks"); -if (!func) - func = dlsym(RTLD_DEFAULT, "__msan_scoped_disable_interceptor_checks"); -if (func) - func(); -``` - -Graphics driver processing should now be totally silent. There will likely -still be a large quantity of reports during application launch and exit, -but once the actual URDE mainloop begins processing, reports should be mostly -limited to the game code itself.