Bethesda VR Address Tools

Tools for converting a Skyrim SSE skse/Fallout4 f4se mod to VR respectively.

Description

This repo consists of two main components: 1. Python files for analyzing c++ code. 2. CSV files that include various data as submodules in skyrimvraddress_library and falloutvraddress_library

Python

vraddresstools.py

This is a python tool that uses the various csv files to analyze c++ code. It is intended to analyze code built using: * Skyrim - commonlibsse for readiness to compile against commonlibvr or commonlibsseng. This currently requires a commonlibvr that can read csv files. * Fallout - commonlibf4 for readiness to compile against commonlibF4/VR. This currently requires a commonlibvr that can read csv files.

Setting up

1. Pull git repo. shell git clone https://github.com/alandtse/vr_address_tools cd vr_address_tools git submodule update --init --recursive # get address libraries
2. Install poetry
3. Install python dependencies shell poetry install

Choosing the game

By default, Skyrim is the default game. To change this, pass in the -f parameter.

shell (vr-address-tools-HCOra_zH-py3.9) PS E:\Documents\source\repos\vr_address_tools> python .\vr_address_tools.py ..\skyrim-drs -f analyze Finished scanning 17 files. rel_ids: 0 offsets: 0 results: 10 \src/DRS.h:65 ID: 35556 FLAT: 0x14366077c WARNING: VR Address undefined. \src/SkyrimUpscaler.cpp:71 ID: 513786 FLAT: 0x143547c48 WARNING: VR Address undefined. \src/SkyrimUpscaler.cpp:80 ID: 517032 FLAT: 0x1468a04b8 WARNING: VR Address undefined. \src/SkyrimUpscaler.cpp:81 ID: 517032 FLAT: 0x1468a04b8 WARNING: VR Address undefined. \src/SkyrimUpscaler.h:24 ID: 527731 FLAT: 0x1469ddb40 WARNING: VR Address undefined. \src/UpscalerHooks.cpp:388 ID: 75595 FLAT: 0x146a005e0 WARNING: VR Address undefined. \src/UpscalerHooks.cpp:397 ID: 75460 FLAT: 0x140b98f60 WARNING: VR Address undefined. \src/UpscalerHooks.cpp:399 ID: 75709 FLAT: 0x1408c4ba4 WARNING: VR Address undefined. \src/UpscalerHooks.cpp:400 ID: 75711 FLAT: 0x14691d8f4 WARNING: VR Address undefined. \src/UpscalerHooks.cpp:408 ID: 79947 FLAT: 0x143669014 WARNING: VR Address undefined. Found 10 items

analyze

Analyze code to determine if uses of rel::id have been defined in database.csv. This allows the mod to be compiled with rel::id's without further changes. Rel::ids using offsets may require further code changes if the VR function has changed. RELOCATION_ID, REL::RELOCATION_ID, REL::ID are supported.

Output will be a tab separated with warnings and potential SSE or VR addresses to check: ```shell

./vraddresstools.py ../CommonLibVR analyze Finished scanning 1,820 files. relids: 8351 offsets: 4013 results: 90 Database matched: 3869 idasuggested: 4234 unverified: 3 mismatch: 16 missing: 4466 include/RE/B/BSFaceGenAnimationData.h:26 REL::ID(25977) SSE: 0x1403c38e0 WARNING: VR Address undefined. include/RE/B/BSFaceGenAnimationData.h:33 REL::ID(25980) SSE: 0x1403c3f00 WARNING: VR Address undefined. include/RE/B/BSMusicManager.h:26 REL::ID(514738) SSE: 0x142ec5ce0 WARNING: VR Address undefined. include/RE/B/BSPointerHandle.h:213 REL::ID(15967) SSE: 0x1401ee670 WARNING: VR Address undefined. include/RE/B/BSPointerHandle.h:220 REL::ID(12204), 1234 SSE: 0x1401329d0 REL::Offset(0x0143180) 0x140143180 WARNING: Offset detected; offset may need to be manually updated for VR include/RE/B/BSPointerHandleManager.h:30 REL::ID(514478) SSE: 0x141ec47c0 WARNING: VR Address undefined. ```

Warning: rel::id with offsets may require change if the underlying function has been changed in VR. This is not necessary if the confidence or status is 4.

cpp REL::Relocation<std::uintptr_t> target{ REL::ID(41659), 0x526 }; In this example, even if 41659 exists in database.csv, the offset to 0x526 may not be the same in VR and will need to be manually updated.

The -d parameter will output a csv format that can be added directly to database.csv. In this example, all ids found were already in the database.

```shell PS E:\Documents\source\repos\vraddresstools> python .\vraddresstools.py ..\skyrim-drs analyze -d Database Load Warning: 24647 mismatch 0x14037f050 0x14037e190 Finished scanning 17 files. rel_ids: 0 offsets: 0 results: 10

Found 0 items ```

generate

Generate a database.csv or release csv. Database.csv can be edited manually or generated. Release csvs should be generated using the tool.

Generate Release csv:

This will take the database.csv and convert it to a release csv.

shell ./vr_address_tools.py . generate -rv 1.1.25 Finished scanning 0 files. rel_ids: 0 offsets: 0 results: 0 Filtered 749049 to 3884 using min_confidence 2 Wrote 3884 rows into version-1.4.15.0.csv with release version 1.1.25

Generate Database.csv

This is intended to scan an existing project that defines both rel::id and rel::offset files with the same namespace. For example, exit-9b's commonsse vr branch was used to generate the initial database.csv file.

shell ./vr_address_tools.py . generate -d Finished scanning 0 files. rel_ids: 0 offsets: 0 results: 0 Filtered 749049 to 3884 using min_confidence 2 Wrote 3888 rows into database.csv with release version 0.0.0

merge.py

Quick script to try to merge the offsets files and some comments files. The primary purpose is to generate seaeoffsets.csv.

CSV Files

Please see submodule READMEs: * Fallout * Skyrim

Porting a Skyrim VR mod

Setup CommonLibVR or CommonLibSSE-NG

1. Download CommonLibVR with csv support.
2. Set environment variable for CommonLibVRPath to CommonLibVR location.
3. Set environment variable for SkyrimVRPath to SkyrimVR path
4. Build CommonLibVR. cmake -B buildVR -S . -DBUILD_SKYRIMVR=ON to confirm it builds.

Modify mod

1. Use vraddresstools to analyze source tree (the tool currently identifies common rel::id formulations. Others may need to be manually found).
2. For any missing rel::ids WARNING: VR Address undefined., modify database.csv with proper address. Consider upstreaming once verified.
3. For any rel::ids with offsets WARNING: Offset detected; offset may need to be manually updated for VR, modify offsets if VR function is different using #ifndef SKYRIMVR as appropriate (see 6).
4. Generate release csv file.
5. Copy release csv to SkyrimVR directory: data/SKSE/Plugins.
6. Use #ifndef SKYRIMVR to identify SSE or VR only sections. For example, the SKSE version check is a common area. Common things (hardest to easiest):
   • x64 Assembly for patchers. This is only needed if functions instructions are not identical. When this happens, the registers used commonly shift in VR vs SSE.
   • Offsets if the function or vtables has changed.
   • Hard coded values such as Skyrim Special Edition like in a path.
   • Version checks
   • Broken functions in VR:
     • ActiveEffectsVisitor
     • Mod Counting
     • Light mod access
7. Modify cmakelists.txt, cmakepresets.json. See example.

Build mod

1. cmake --preset vs2022-windows-vcpkg-vr
2. cmake --build buildvr --config Release or open buildvr/modname.sln. Build release and copy to SkyrimVR.

Contributions are welcome!

If you want to contribute to this please read the Contribution guidelines