1
0
Fork 0
mirror of https://github.com/zeldaret/oot.git synced 2024-11-28 19:25:27 +00:00

Add installation instructions to the README (+ minor improvements) (#100)

This commit is contained in:
Roman971 2020-05-01 03:47:42 +02:00 committed by GitHub
parent 5525365f7f
commit 9bb151006a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 164 additions and 40 deletions

2
.gitignore vendored
View file

@ -42,5 +42,5 @@ tools/asmsplitter/c/*
*.ci4.png
*.ci8.png
#Per-user configuration
# Per-user configuration
.python-version

173
README.md
View file

@ -1,23 +1,174 @@
# Legend of Zelda: Ocarina of Time Master Quest (debug)
# The Legend of Zelda: Ocarina of Time
```diff
- WARNING! -
The ROM this repository builds while has a matching checksum cannot be 'shifted' due
to hardcoded pointers which have yet to be dumped. Thus this repository is currently
in an experimental and research phase and cannot currently be used traditionally as a
source code base for general changes.
The ROM this repository builds cannot be 'shifted', primarily due to some hardcoded pointers which have yet
to be dumped. Thus this repository is currently in an experimental and research phase and cannot yet be used
traditionally as a source code base for general changes.
```
This repo does not include all assets necessary for compiling the ROM. A prior copy of the game is required to extract the required assets.
This is a disassembly and decompilation of Legend of Zelda: Ocarina of Time Master Quest (debug)
This is a WIP decompilation of The Legend of Zelda: Ocarina of Time.
The purpose of the project is to recreate a source code base for the game from scratch, using information found inside the game along with static and/or dynamic analysis.
The only build currently supported is Master Quest (Debug), but other versions are planned to be supported.
It builds the following ROM:
* zelda_ocarina_mq_dbg.z64 `md5: f0b7f35375f9cc8ca1b2d59d78e35405`
Please refer to the Getting Started guide in the Wiki for setup instructions.
**Note:** This repository does not include any of the assets necessary to build the ROM.
A prior copy of the game is required to extract the needed assets.
Website: https://zelda64.dev/
Website: <https://zelda64.dev/>
Discord: https://discord.zelda64.dev
Discord: <https://discord.zelda64.dev>
## Installation
### Windows
For Windows 10, install WSL and a distribution by following this
[Windows Subsystem for Linux Installation Guide](https://docs.microsoft.com/en-us/windows/wsl/install-win10).
We recommend using Debian or Ubuntu 18.04 Linux distributions.
For older versions of Windows, install a Linux VM or refer to [Docker](#Docker) instructions.
### macOS
For macOS, install a Linux VM or refer to [Docker](#Docker) instructions.
### Linux (Native or under WSL / VM)
#### 1. Install build dependencies
The build process has the following package requirements:
* git
* build-essential
* binutils-mips-linux-gnu
* python3
Under Debian / Ubuntu (which we recommend using), you can install them with the following commands:
```bash
sudo apt-get update
sudo apt-get install git build-essential binutils-mips-linux-gnu python3
```
#### 2. Download qemu-irix
Download qemu-irix.zip from the Releases section in the repository. Extract it to a folder of your choosing.
#### 3. Set environment variables
Open up your .bashrc file (~/.bashrc), scroll to the bottom, and add the following, replacing the paths as necessary:
```text
export QEMU_IRIX="path/to/your/qemu-irix"
export MIPS_BINUTILS_PREFIX=mips-linux-gnu-
```
Save and close/reopen your terminal window.
#### 4. Clone the repository
Clone `https://github.com/zeldaret/oot.git` where you wish to have the project, with a command such as:
```bash
git clone https://github.com/zeldaret/oot.git
```
#### 5. Prepare a base ROM
Copy over your copy of the Master Quest (Debug) ROM inside the root of this new project directory.
Rename the file to "baserom_original.z64" or "baserom_original.n64", depending on the original extension.
#### 6. Setup the ROM and build process
Setup and extract everything from your ROM with the following command:
```bash
make setup
```
This will generate a new ROM called "baserom.z64" that will have the overdump removed and the header patched.
It will also extract the individual assets from the ROM.
#### 7. Build the ROM
Run make to build the ROM.
Make sure your path to the project is not too long, otherwise this process may error.
```bash
make
```
If all goes well, a new ROM called "zelda_ocarina_mq_debug.z64" should be built and the following text should be printed:
```bash
zelda_ocarina_mq_dbg.z64: OK
```
If you instead see the following:
```bash
zelda_ocarina_mq_dbg.z64: FAILED
md5sum: WARNING: 1 computed checksum did NOT match
```
This means that the built ROM isn't the same as the base one, so something went wrong or some part of the code doesn't match.
### Docker
#### 1. Setup requirements
To use Docker, you'll need either Docker Desktop or Docker Toolbox installed and setup based on your system.
You'll also need to prepare a local version of the project with a copied base ROM (see Step 4 and 5 of the Linux instructions).
#### 2. Create the docker image
From inside your local project, run the following command:
```bash
docker build . -t oot
```
#### 3. Start the container
##### Option A: With docker run
To start the container, you can mount your local filesystem into the docker container and run an interactive bash session.
```bash
docker run -it --rm --mount type=bind,source="$(pwd)",destination=/oot oot /bin/bash
```
##### Option B (only for macOS): With docker-sync
Prerequisite for this option: Install docker-sync with `gem install docker-sync`
To start docker-sync and the development container, use `docker-sync-stack start`
After a lot of waiting, you'll see something like "Attaching to oot_oot_1".
This means the container is ready.
Then it's time to log into the container to begin working.
Note that this will be done in another tab while you leave the docker-sync tab going.
To get the container id, use `docker container ls` and use the ID from the container with image oot:latest in the following command:
`docker exec-it <CONTAINER-ID> /bin/bash` You're in.
> Note: When done working, type Ctrl+c on the docker-sync tab to close the container and docker-sync.
#### 4. Setup and Build the ROM
Once inside the container, you can follow Step 6 and 7 of the Linux instructions to setup and build the ROM, or run any other command you need.
## Contributing
All contributions are welcome. This is a group effort, and even small contributions can make a difference.
Some tasks also don't require much knowledge to get started.
Most discussions happen on our [Discord Server](https://discord.zelda64.dev), where you are welcome to ask if you need help getting started, or if you have any questions regarding this project and other decompilation projects.

View file

@ -1,27 +0,0 @@
## Developing on OSX
#### Requirements
* Docker Desktop (for OSX)
* docker-sync (`gem install docker-sync`)
* a set-up baserom (see general setup guide / wiki for more details)
#### Build the docker image
`docker build . -t oot`
#### Start docker-sync and the development container
`docker-sync-stack start`
After a lot of waiting, you'll see something like "Attaching to oot_oot_1". This means the container is ready.
#### Log into the container to begin working
Note: this will be done in another tab while you leave the docker-sync tab going.
To get the container id, use `docker container ls` and use the ID from the container with image oot:latest in the following command
`docker exec-it <CONTAINER-ID> /bin/bash` You're in.
Run `make setup` followed by `make`, and you're off to the races!
#### When done working
Type Ctrl+c on the docker-cync tab to close the container and docker-sync.

View file

@ -1 +1 @@
Thanks to z64me and CrookedPoe for their actor documentation. https://github.com/CrookedPoe/z64-rw
Thanks to z64me and CrookedPoe for their actor documentation. <https://github.com/CrookedPoe/z64-rw>