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 skyrim_vr_address_library and fallout_vr_address_library

Python

vr_address_tools.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.

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

poetry install

Choosing the game

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

(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:

> ./vr_address_tools.py ../CommonLibVR analyze
Finished scanning 1,820 files. rel_ids: 8351 offsets: 4013 results: 90
Database matched: 3869 ida_suggested: 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.

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.

PS E:\Documents\source\repos\vr_address_tools> python .\vr_address_tools.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.

./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.

./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 se_ae_offsets.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 vr_address_tools 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

---