dasaav-dsv / liber

ELDEN RING API library with a focus on binary compatibility and safety

libER ELDEN RING API library

libER is an ELDEN RING Application Programming Interface (API) library that aims to provide a safe C++ interface for the game by leveraging binary compatibility between different versions of the Microsoft Visual Compiler.

The ELDEN RING executable has been built with Visual Studio 2015, which also happens to be the earliest Microsoft guarantees binary compatibility for all future compiler and standard library versions onwards. For libER, this means the C++ standard library features can be used wherever they are used in ELDEN RING, as long as libER is compiled with MSVC or another compatible compiler.

Being able to use the STL provides the safety and guarantees of the standard library and greatly simplifies reversing and documenting efforts. Settling on the MSVC standard library (even if only because ELDEN RING uses it) means a stable ABI and API for the game. This choice is somewhat limiting, but also defines a common standard for projects that use libER.

NOTE: The clang-cl toolchain may be used instead of the MSVC compiler, provided the Visual Studio STL is used.

Features

• Written in modern C++20

• Byte perfect documentation of ELDEN RING type layouts

• Type safety while exposing ELDEN RING's own functionality

• Thread safety where it is expected, asynchronous execution with native ELDEN RING tasks

• Non-invasive modifications to ELDEN RING, custom allocator replacement without hooks or code patches (!)

• No pattern matching or other fallible runtime analysis

• Symbol definition files, separated by game version

• Possibility to pull symbol definitions from GitHub on a game version mismatch

  NOTE: libER_updater.exe must be in "ELDEN RING/Game" or in PATH

• Familiar stl-like naming, or the original ELDEN RING naming where it is known

• Doxygen documentation and widespread use of comments in the codebase

• Introspection of the ELDEN RING engine, tasks, memory allocation, file loading...

• Support for both static and dynamic linking

Installation

libER is an ELDEN RING API, not a mod by itself. You can include libER in your project with CMake or by linking to the library files.

Building libER

Requirements: git, CMake, Visual Studio with any toolchain

git clone --recurse-submodules https://github.com/Dasaav-dsv/libER.git
cd libER
mkdir build
cd build
cmake ..
cmake --build . --config Release

NOTE: If you wish to include libER in your CMake project, you must define "_ITERATOR_DEBUG_LEVEL" as "0", otherwise the STL containers will not be compatible in Debug mode.

add_subdirectory("[libER INSTALL DIR]" "libER")

# Set iterator debug level to 0 for ELDEN RING ABI compatibility
add_definitions(-D_ITERATOR_DEBUG_LEVEL=0)
target_compile_features("[YOUR TARGET]" PRIVATE cxx_std_20)

Examples can be built much like base libER.

Usage

libER is meant to be a base for mods and other libraries for ELDEN RING. It wraps the ELDEN RING functionality in a safe interface that can be further abstracted. If libER is dynamically linked against, libER.dll must be in "ELDEN RING/Game" or in PATH. If you wish for automatic symbol updates to work, libER_updater.exe must be likewise findable.

Currently, "./examples" has examples of using ELDEN RING tasks and type reflection, with more to come in the future.

The libER documentation is currently hosted at https://dasaav-dsv.github.io/libER/

libER replaces the standard allocators used by ELDEN RING. This both improves performance and more importantly allows for memory allocation before game initialization in a way that is compatible with the game.

Namespaces

libER uses two main namespaces:

• namespace from describes ELDEN RING
• namespace liber contains libER implementation details

Contributing

libER is open to contributions. You may file issues, open pull requests, fork the repository etc. We are always looking for more contributors.

Please use clang-format and annotate your code with doxygen (and normal) comments.

Keep a consistent style with the rest of libER:

• Known ELDEN RING typenames and namespaces are kept as is
• Unknown and libER implementation names should use lowercase snake case
• Keep the directory structure consistent

License

Permissive Apache 2.0 with LLVM exception.

liber's Issues

[FR] control crafting menu sort

when you press L3 in the crafting menu, you can select an alternate sort type which includes the category separator bars from the regular inventory

this is reset every time you close and reopen the menu

controlling this via libER would be cool

Find a way to attach tasks to preexisting steppers (stateful tasks that already happen in ELDEN RING)

Tests (on the ELDEN RING exe?)

Somehow, run tests on ELDEN RING from GitHub actions

Symbol loading documentation

The way symbols are stored in the binary, loaded and downloaded should be documented

Access + modify dropped bloodstain with runes in it

Get how many runes are in the bloodstain, read/change its location, place it or remove it, etc

Support doxygen documentation generation

Rewrite comments/annotations to support doxygen, and add extra ones where needed

Accessing/modifying game settings (such as "Tutorials", "Blood")

Update .mtd and .ffx extensions to their ELDEN RING counterparts

ER does not use .mtd and .ffx, but .matbin and .fxr. The internal names are a leftovers from earlier games (and are misleading)

Think over clang-format options

The current clang-format formatting options may not be ideal in terms of visibility and consistency. Rethink and apply new clang-format formatting to the entire codebase.

[FR] control game pause state

If you think it's a good idea, I might dump some feature requests in here sometimes, use cases I've seen elsewhere or have myself.

Not in a "ADD THIS NOW PLSSSSS" kinda desperate way, just to catalogue what use cases exist.

LOD textures loaded even while close up in some locations.

In certain locations, the low level of detail textures seem to be mistakenly loaded instead of higher detail versions. This can be easily noticed in the entrance to Stormveil, in the walk from Margit's arena to the castle gate, as the textures of the ground switch to a much higher detail version while walking towards the castle, and also switch back to low detail versions when walking away.
I don't know what could be causing this, but from my testing this always happens while libER is loaded.

Check DLTX::FD4BasicHashString's string_hash for correctness

const T* str may instead be pointing to a C string?

Extend hardcoded weapon shaders & trace sfx overrides

More wishlist stuff / "did you know this exists" stuff.

In SpEffectVfxParam, you can apply several fun things to your weapons:

traceSfxIdOffsetType

Lets you change the default weapon trails to Magic, Fire, Lightning etc.
How it works is as follows:

• Every weapon under EquipParamWeapon has traceSfxId entries, such as 401000. This is an FXR ID corresponding to a vfx file.
• The int under traceSfxIdOffsetType offsets this id by 10000 + ((traceSfxIdOffsetType - 1) * 1000).
• Example: You use a Fire Grease, which has a traceSfxIdOffsetType SpEffectVfx with value 2, which stands for Fire. Your weapon will now use 401000 + 10000 + ((2 - 1) * 1000) = 412000 as its swing trail.

This is cool, however traceSfxIdOffsetType is arbitrarily restricted to a fixed list of values. Other values have no effect, even if you add VFX at those IDs. This doesn't make much sense due to the otherwise very dynamic nature of the offset calculation.

Make it possible to enter an arbitrary number! That way we can create more trails whenever we want.

soulParamIdForWepEnchant

Lets you apply a PhantomParam-esque visual shader overlay to your weapon. For example, when you use Determination/Royal Knight's Resolve, your weapon glows white, like a Dark Souls cooperator.

This is, again, based on an enum which vaguely corresponds to the traceSfx ones, but only vaguely.

There does not appear to be any way to edit these phantomparam looks, nor to add additional ones. It's a hardcoded list of fixed looks. Again, this would be appreciated.

Doxygen examples

Doxygen documentation needs examples and code snippets