Update README.md

This commit is contained in:
Luke Street 2022-11-23 10:07:42 -05:00
parent d333608cd6
commit 2644c01123
2 changed files with 9 additions and 103 deletions

View File

@ -7,9 +7,10 @@
![Metaforce screenshot](assets/metaforce-screen1.png) ![Metaforce screenshot](assets/metaforce-screen1.png)
### Download ### Download
This project is currently in **Alpha** state, so expect bugs. This project is currently in **alpha** state.
Builds available at [https://releases.axiodl.com](https://releases.axiodl.com). Builds are currently unavailable while the project undergoes large changes.
### Platform Support ### Platform Support
* Windows 10 (64-bit, D3D11 / Vulkan) * Windows 10 (64-bit, D3D11 / Vulkan)
@ -17,10 +18,10 @@ Builds available at [https://releases.axiodl.com](https://releases.axiodl.com).
* Linux (Vulkan) * Linux (Vulkan)
* Follow [this guide](https://github.com/lutris/docs/blob/master/InstallingDrivers.md) to set up Vulkan & appropriate drivers for your distro. * 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: Windows:
- Open `metaforce-gui.exe` - Open `metaforce.exe`
macOS: macOS:
- Open `Metaforce.app` - Open `Metaforce.app`
@ -29,26 +30,7 @@ Linux:
- Ensure AppImage is marked as executable: `chmod +x Metaforce-*.AppImage` - Ensure AppImage is marked as executable: `chmod +x Metaforce-*.AppImage`
- Open `Metaforce-*.AppImage` - Open `Metaforce-*.AppImage`
### CLI usage (GC versions) #### CLI options (non-exhaustive)
* 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)
* `-l`: Enable console logging * `-l`: Enable console logging
* `--warp [worldid] [areaid]`: Warp to a specific world/area. Example: `--warp 2 2` * `--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 \ 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 \ 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 \ 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 * 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 * Fedora packages
``` ```
cmake vulkan-headers ninja-build clang-devel llvm-devel libpng-devel qt6-qtbase-devel cmake vulkan-headers ninja-build clang-devel llvm-devel libpng-devel
qt6-linguist qt6-qttools-devel qt6-qtscxml-devel qt6-qtsvg-devel qt6-qt5compat-devel
``` ```
* It's also important that you install the developer tools and libraries * It's also important that you install the developer tools and libraries
``` ```
@ -151,21 +132,3 @@ cmake -G Xcode ../metaforce
``` ```
Then open `metaforce.xcodeproj` 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

View File

@ -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 <dlfcn.h>` 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.