CommonLibSF

https://github.com/starfield-reverse-engineering/commonlibsf
Admin
A collaborative reverse-engineered library for Starfield, providing a static dependency to replace...
Tokens:7,072
Snippets:14
Trust Score:4.9
License:GPL-3.0
Update:1 year ago
Show doc for...
Tokens:
Raw
### Installation Rules

Source: https://github.com/starfield-reverse-engineering/commonlibsf/blob/main/CMakeLists.txt

Configures the installation process for the built library and its CMake configuration files. It installs the target library, exports targets for other CMake projects, generates a configuration file, and installs header directories.

```cmake
install(
  TARGETS ${PROJECT_NAME}
  EXPORT ${PROJECT_NAME}-targets
)

install(
  EXPORT ${PROJECT_NAME}-targets
  NAMESPACE ${PROJECT_NAME}::
  DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/${PROJECT_NAME}
)

configure_file(
  cmake/config.cmake.in
  ${PROJECT_NAME}Config.cmake
  @ONLY
)

install(
  FILES cmake/CommonLibSF.cmake
  DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/${PROJECT_NAME}
)

install(
  FILES ${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}Config.cmake
  DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/${PROJECT_NAME}
)

install(
  DIRECTORY
  include/RE
  include/REL
  include/REX
  include/SFSE
  DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
)
```

--------------------------------

### Lumina Configuration for IDA Pro

Source: https://github.com/starfield-reverse-engineering/commonlibsf/wiki/Importing-and-sharing-types-with-IDA

Configuration parameters for Lumina, a tool that allows sharing of definitions between IDA instances. This snippet shows how to set the host, port, and TLS settings for Lumina.

```ini
// Lumina related parameters
LUMINA_HOST = "18.144.142.42";
LUMINA_PORT = 1234;
LUMINA_TLS = NO;
//LUMINA_MIN_FUNC_SIZE = 32;
```

--------------------------------

### CommonLibSF Project Setup and Configuration

Source: https://github.com/starfield-reverse-engineering/commonlibsf/blob/main/CMakeLists.txt

This snippet details the CMake configuration for the CommonLibSF project. It sets the minimum required CMake version, defines project-specific options like REX_OPTION_INI and SFSE_SUPPORT_XBYAK, establishes C++ standards (C++23), and enforces out-of-source builds to maintain a clean build environment.

```CMake
cmake_minimum_required(VERSION 3.30)
message("Using toolchain file ${CMAKE_TOOLCHAIN_FILE}.")

# singleton target across multiple projects
if(TARGET CommonLibSF)
  return()
endif()

# options if not defined
option(REX_OPTION_INI "Enables ini config support for REX." OFF)
option(REX_OPTION_JSON "Enables json config support for REX." OFF)
option(REX_OPTION_TOML "Enables toml config support for REX." OFF)
option(SFSE_SUPPORT_XBYAK "Enables trampoline support for xbyak." OFF)
option(SFSE_BUILD_TESTS "Builds the tests." OFF)

# info
project(
  CommonLibSF
  LANGUAGES CXX
)

# standards & flags
set(CMAKE_CXX_STANDARD 23)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_OPTIMIZE_DEPENDENCIES ON)

include(GNUInstallDirs)

# out-of-source builds only
if(${PROJECT_SOURCE_DIR} STREQUAL ${PROJECT_BINARY_DIR})
  message(FATAL_ERROR "In-source builds are not allowed.")
endif()
```

--------------------------------

### SFSEPluginVersion Metadata Declaration for Starfield Plugins

Source: https://github.com/starfield-reverse-engineering/commonlibsf/wiki/Using-CommonLibSF

The SFSEPluginVersion function declares metadata about the plugin, such as its version, name, and compatibility, for SFSE during the loading process. This example shows how to define these details in a header file.

```cpp
#pragma once

namespace Plugin
{
    using namespace std::string_view_literals;

    static constexpr auto Name{"PluginName"sv};
    static constexpr auto Author{"AuthorName"sv};
    static constexpr auto Version{
        REL::Version{0, 0, 1, 0}
    };
}

SFSEPluginVersion = []() noexcept {
    SFSE::PluginVersionData data{};

    data.PluginVersion(Plugin::Version.pack());
    data.PluginName(Plugin::Name);
    data.AuthorName(Plugin::Author);
    data.UsesAddressLibrary(true);
    data.IsLayoutDependent(true);
    data.CompatibleVersions({ SFSE::RUNTIME_LATEST });

    return data;
}();
```

--------------------------------

### IDA Pro Clang Header Parsing Configuration

Source: https://github.com/starfield-reverse-engineering/commonlibsf/wiki/Importing-and-sharing-types-with-IDA

Configure IDA Pro's compiler settings to parse C++ headers using Clang for CommonLibSF. This involves setting the source parser, include paths, and compiler arguments to correctly interpret the project's headers and types.

```APIDOC
IDA Compiler Settings for CommonLibSF Header Parsing:

1.  **Source parser**: Set to `clang`.
2.  **Includes**: Set to `C:\\Program Files\\Microsoft Visual Studio\\2022\\Professional\\VC\\Tools\\MSVC\\<version>\\include;<path-to-CommonLibSF>\\build\\build-debug-clang-cl-ninja-vcpkg\\vcpkg_installed\\x64-windows-static-md\\include;<path-to-CommonLibSF>\\include`.
    *   This path requires replacing `<version>` with your specific Visual Studio version and `<path-to-CommonLibSF>` with the actual directory where CommonLibSF is cloned.
3.  **Arguments**: Set to `-x c++ -std=c++20 -fms-compatibility -D_CRT_USE_BUILTIN_OFFSETOF`.

After configuration, use `File->Load File->Parse C header file...` and select `include\RE\Starfield.h` to import types.
```

--------------------------------

### SFSEPluginLoad Entry Point for Starfield Plugins

Source: https://github.com/starfield-reverse-engineering/commonlibsf/wiki/Using-CommonLibSF

The SFSEPluginLoad function is the main entry point for SFSE to load a DLL plugin. It is typically a macro wrapper that initializes the plugin and returns a boolean indicating success.

```cpp
SFSEPluginLoad(const SFSE::LoadInterface* sfse)
{
    Init(sfse);

    // do stuff

    return true;
}
```

--------------------------------

### Project Dependencies and Source Discovery

Source: https://github.com/starfield-reverse-engineering/commonlibsf/blob/main/CMakeLists.txt

This snippet finds required packages like spdlog, recursively discovers source files from include and src directories, excludes a specific header, and groups the sources for the build target.

```cmake
find_package(spdlog CONFIG REQUIRED)

file(
  GLOB_RECURSE
  SOURCES
  CONFIGURE_DEPENDS
  ${CMAKE_CURRENT_SOURCE_DIR}/include/*
  ${CMAKE_CURRENT_SOURCE_DIR}/src/*
)
list(REMOVE_ITEM SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/include/SFSE/Impl/PCH.h)

source_group(
  TREE ${CMAKE_CURRENT_SOURCE_DIR}
  FILES ${SOURCES}
)
```

--------------------------------

### SFSE Utilities: write_vfunc

Source: https://github.com/starfield-reverse-engineering/commonlibsf/wiki/Miscellanous-Explanatory-Stuff

Enables writing virtual method swaps by specifying the destination class and a hook class. Variants exist for selecting specific vtables.

```cpp
class MyHook
{
public:
    static HookReturnType Thunk(<args...>); // reverse-engineered function signature

    inline static REL::Relocation<decltype(&Thunk)> func;

    static constexpr std::size_t idx{ 42 }; // vtable index of the vfunc we want to swap
}
```

--------------------------------

### Include CommonLibSF using xrepo (xmake)

Source: https://github.com/starfield-reverse-engineering/commonlibsf/wiki/Using-CommonLibSF

Instructions for adding CommonLibSF as a dependency in your xmake project. This involves adding a custom repository and requiring the commonlibsf package.

```lua
-- add commonlibsf-xrepo repository
add_repositories("re https://github.com/Starfield-Reverse-Engineering/commonlibsf-xrepo")

-- require package dependencies
add_requires("commonlibsf")

target("name")
...
    -- bind packages to the target
    add_packages("commonlibsf")
```

--------------------------------

### Library Target Creation and Configuration

Source: https://github.com/starfield-reverse-engineering/commonlibsf/blob/main/CMakeLists.txt

This section conditionally creates a static library target for the project. If tests are enabled, it includes test sources; otherwise, it builds the main library. It then calls the `configure_target` function to apply all defined settings.

```cmake
if(SFSE_BUILD_TESTS)
  # add a custom library target that just builds test.cpp
  add_library(
    ${PROJECT_NAME}-test
    STATIC
    ${SOURCES}
    ${CMAKE_CURRENT_SOURCE_DIR}/test/test.cpp
  )
  configure_target(${PROJECT_NAME}-test)
  set(PROJECT_NAME ${PROJECT_NAME}-test)
else()
  add_library(
    ${PROJECT_NAME}
    STATIC
    ${SOURCES}
  )
  add_library(${PROJECT_NAME}::${PROJECT_NAME} ALIAS ${PROJECT_NAME})
  configure_target(${PROJECT_NAME})
endif()
```

--------------------------------

### SFSE Commonlibsf CMake Plugin Command

Source: https://github.com/starfield-reverse-engineering/commonlibsf/wiki/Miscellanous-Explanatory-Stuff

A custom CMake command to automate plugin declaration and SFSE integration tasks, generating Plugin.h and exporting SFSEPlugin_Version.

```cmake
add_commonlibsf_plugin(
  <plugin_name>
  AUTHOR <author_name>
  VERSION <plugin_version>
  MINIMUM_SFSE_VERSION <sfse_version>
  [USE_ADDRESS_LIBRARY <bool>]
  [USE_SIGNATURE_SCANNING <bool>]
  [STRUCT_DEPENDENT <bool>]
  [EXCLUDE_FROM_ALL <bool>]
  [COMPATIBLE_RUNTIMES <runtime1> <runtime2> ...]
  [SOURCES <header1> <header2> ... <source1> <source2> ...]
)
```

```cmake
add_commonlibsf_plugin(
  ${PROJECT_NAME}
  AUTHOR AuthorName
  SOURCES ${headers} ${sources}
)
```

--------------------------------

### Configure Target Function

Source: https://github.com/starfield-reverse-engineering/commonlibsf/blob/main/CMakeLists.txt

Defines a reusable function to configure build targets. It sets compile definitions (e.g., Windows version, feature flags), applies specific compiler options for MSVC and Clang, manages include directories, sets up precompiled headers, and links necessary libraries.

```cmake
function(configure_target TARGET_NAME)
  if(SFSE_SUPPORT_XBYAK)
    find_package(xbyak CONFIG REQUIRED)
  endif()

  target_compile_definitions(
    ${TARGET_NAME}
    PUBLIC
    WINVER=0x0A00 # windows 10, minimum supported version by starfield
    _WIN32_WINNT=0x0A00
    "$<$<BOOL:${REX_OPTION_INI}>:REX_OPTION_INI=1>"
    "$<$<BOOL:${REX_OPTION_JSON}>:REX_OPTION_JSON=1>"
    "$<$<BOOL:${REX_OPTION_TOML}>:REX_OPTION_TOML=1>"
    "$<$<BOOL:${SFSE_SUPPORT_XBYAK}>:SFSE_SUPPORT_XBYAK=1>"
    WIN32_LEAN_AND_MEAN
    NOMINMAX
    _ITERATOR_DEBUG_LEVEL=0
  )

  # FIXME: https://gitlab.kitware.com/cmake/cmake/-/issues/24922
  set_property(
    TARGET ${TARGET_NAME}
    PROPERTY VS_USER_PROPS
    ${CMAKE_CURRENT_SOURCE_DIR}/cmake/build_stl_modules.props
  )

  target_compile_options(
    ${TARGET_NAME}
    PUBLIC
    /bigobj # support large object file format
    /wd4005 # macro redefinition
    /wd4068 # unknown pragma
    /wd4200 # nonstandard extension used: zero-sized array in struct/union
    /wd4201 # nonstandard extension used: nameless struct/union
  )

  if(CMAKE_CXX_COMPILER_FRONTEND_VARIANT STREQUAL MSVC AND CMAKE_CXX_COMPILER_ID STREQUAL Clang)
    set(CLIBSF_COMPILEFLAGS_RELEASE /Ob3 /GR- /Gw /Qvec -flto -fsplit-lto-unit -fvirtual-function-elimination -fwhole-program-vtables)

    target_compile_options(
      ${TARGET_NAME} PRIVATE
      /Zc:alignedNew
      /Zc:char8_t
      /Zc:sizedDealloc
      /Zc:strictStrings
      /Zc:threadSafeInit
      -fansi-escape-codes
      -fcolor-diagnostics
      -fcomplete-member-pointers
      -fexperimental-library
      -fforce-emit-vtables
      -fms-compatibility
      -fms-extensions
      -fstrict-aliasing
      -Wno-overloaded-virtual
      -Wno-delete-non-abstract-non-virtual-dtor
      -Wno-inconsistent-missing-override
      -Wno-reinterpret-base-class
      -Wno-return-type
      -Wno-invalid-offsetof
      -Wno-switch
      -Wno-unused-command-line-argument
      $<$<CONFIG:Release>:${CLIBSF_COMPILEFLAGS_RELEASE}> 
    )
  elseif(CMAKE_CXX_COMPILER_FRONTEND_VARIANT STREQUAL MSVC AND CMAKE_CXX_COMPILER_ID STREQUAL MSVC)
    set(CLIBSF_COMPILEFLAGS_RELEASE /fp:fast /Ob3 /GL /GR- /Gw /Qpar)

    target_compile_options(
      ${TARGET_NAME}
      PRIVATE
      /cgthreads8
      /diagnostics:caret
      /jumptablerdata
      /MP
      /W4
      /Zc:__cplusplus
      /Zc:enumTypes
      /Zc:inline
      /Zc:templateScope
      $<$<CONFIG:Release>:${CLIBSF_COMPILEFLAGS_RELEASE}> 
    )
  endif()

  target_include_directories(
    ${TARGET_NAME}
    PUBLIC
    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
    $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
  )

  target_precompile_headers(
    ${TARGET_NAME}
    PRIVATE
    include/SFSE/Impl/PCH.h
  )

  target_link_libraries(
    ${TARGET_NAME}
    PUBLIC
    spdlog::spdlog
    advapi32.lib
    bcrypt.lib
    dbghelp.lib
    dxgi.lib
    ole32.lib
    version.lib
    ws2_32.lib
  )
endfunction()
```

--------------------------------

### Include CommonLibSF using git submodule (Shell)

Source: https://github.com/starfield-reverse-engineering/commonlibsf/wiki/Using-CommonLibSF

Commands to add CommonLibSF as a git submodule to your project directory.

```ps
git submodule add https://github.com/Starfield-Reverse-Engineering/CommonLibSF extern/CommonLibSF
git submodule update -f --init
```

--------------------------------

### Include CommonLibSF using git submodule (CMake)

Source: https://github.com/starfield-reverse-engineering/commonlibsf/wiki/Using-CommonLibSF

Steps to integrate CommonLibSF into your CMake project using a git submodule. This involves adding the submodule and linking it to your target.

```cmake
add_subdirectory(extern/CommonLibSF)
target_link_libraries(
  ${PROJECT_NAME}
  PRIVATE
  CommonLibSF::CommonLibSF
)
```
Tokens:
Raw