C++ language, by example

C++ here is not trying to be clever. It is trying to do three things a garbage-collected language never asks of you: control the exact bytes of a struct, keep objects alive for a precise lifetime, and generate code at compile time instead of runtime.

The reading surface

Nearly everything is wrapped in a nested namespace, written with the C++17 shorthand. The nesting is organisational, not semantic — you can usually read the innermost name and ignore the rest:

namespace Libs::LibKernel::Memory {   // Libs { LibKernel { Memory { ... } } }
  ...
}

using aliases replace typedef and are everywhere. The ones that look alarming are function-pointer aliases — read them right to left:

using callback_func_t = void (*)(uintptr_t addr, size_t size);
//  "callback_func_t" is a pointer to a function that takes
//   (uintptr_t, size_t) and returns void.

At namespace scope, static gives a function internal linkage; an anonymous namespace can do the same. Internal linkage does not prevent guest access through a registered function pointer. To understand an HLE entry point, check both its linkage and its LIB_FUNC registration. Absence of static alone does not make a function a public API.

`auto` — the default spelling

auto deduces the type from the initialiser. The tree writes const auto for anything read-only, const auto& to avoid copying, and auto* when the initialiser is a pointer. It never deduces a reference unless you write the & yourself:

const auto aligned_stack_top = reinterpret_cast<uintptr_t>(stack_top) & ~static_cast<uintptr_t>(0x0f);
const auto guest_rsp         = aligned_stack_top - 2u * sizeof(uintptr_t);

auto* addr = reinterpret_cast<T*>(ptr);   // auto* keeps the pointerness

Think of auto as TypeScript's let x = ... where the type is always inferred — except there is no : Type annotation syntax for it. When a declaration says const auto&, read "a reference that I will not copy and cannot modify".

`constexpr` — computing at build time

constexpr marks a value (or function) that can be evaluated when the binary is built. src/loader/elf.h opens with a wall of them, because the ELF format's magic numbers never change:

constexpr char    ELFCLASS64    = 2;
constexpr int     EM_X86_64     = 62;
constexpr int     EV_CURRENT    = 1;
constexpr Elf64_Word PT_LOAD     = 1;
constexpr Elf64_Sxword DT_NEEDED = 0x00000001;
// a compile-time database of the format, used to parse game modules

Its partner is static_assert, which fails the build if the condition is false. The tree uses it as a contract on struct sizes — the ultimate guard against the compiler inserting padding you did not ask for:

struct VirtualQueryInfo { ... };

static_assert(sizeof(VirtualQueryInfo) == 72, "VirtualQueryInfo struct size is incorrect");

Then the genuinely modern part. src/common/subsystems.h uses consteval (a function that must run at compile time), if constexpr (compile-time branching) and a requires clause (asking "does this type have a member?"):

template <typename Lifecycle>
static consteval Callback ShutdownCallback() {
    if constexpr (requires { Lifecycle::shutdown; }) {
        return Lifecycle::shutdown;
    }
    return nullptr;
}

This is a type that may or may not provide a shutdown member; the code adapts at compile time instead of runtime. It feeds the wider pattern of a Lifecycle descriptor — a struct of static constexpr members that describes a subsystem to a registry:

struct Lifecycle {
    static constexpr const char* name       = "Memory";
    static constexpr auto        initialize = Libs::LibKernel::Memory::Initialize;
    static constexpr auto        shutdown   = Libs::LibKernel::Memory::Shutdown;
};

static constexpr auto initialize = SomeFunction; stores a function pointer as a compile-time constant. The pointer is a compile-time constant; the subsystem registry still records successful lifecycle entries at runtime for reverse-order shutdown.

Templates — code that writes code

A template is a recipe instantiated at compile time for each combination of arguments. Three shapes appear constantly:

1. Function templates that deduce their own sizes. In OpcodeTable.h, the array size is captured by passing the array by reference — const Entry (&table)[N] — so FindOpcode works for any table without the caller saying how long it is:

template <typename Entry, size_t N>
constexpr const Entry* FindOpcode(const Entry (&table)[N], uint32_t encoding) {
    for (const auto& entry: table) {
        if (entry.encoding == encoding) {
            return &entry;
        }
    }
    return nullptr;
}

2. Class templates with non-type parameters. Template arguments do not have to be types — they can be numbers. BitArray<N> is a fixed-size bit set, and the MultiLevelPageTable for the texture cache is configured entirely by numbers:

template <typename EntryT, size_t PageBits = 20, size_t AddressSpaceBits = 40,
          size_t FirstLevelBits = 10>
class MultiLevelPageTable final {
    static_assert(AddressSpaceBits < 64);
    static_assert(PageBits < AddressSpaceBits);
    ...
};

3. Explicit specialisation. When one combination needs a hand-written version. vaContext.h has a bespoke reader for 32-byte float4 arguments that the generic path cannot handle:

template <>
inline VaFloatX4 VaArg_reg_save_area_fp<VaFloatX4, 32>(VaList* l) {
    // two 16-byte registers stitched into one float4
    ...
}

A function template describes a family of functions; a class template describes a family of types. Arguments select a specialization. Instantiation errors often include a chain of call sites: start at the first relevant diagnostic and follow that chain to the unsupported operation, rather than assuming every template error is located at the caller.

Move semantics and perfect forwarding

After you understand the B3 owner transfer, read src/common/uniqueFunction.h, a move-only, type-erased callable. Type erasure stores different callable types behind one interface. Read the constructor, owned implementation object and invocation path separately:

template <typename Result, typename... Args>            // variadic template
class UniqueFunction {
    ...
    UniqueFunction(UniqueFunction&&) noexcept            = default;  // movable
    UniqueFunction(const UniqueFunction&)                = delete;   // not copyable

    template <typename Function>
    UniqueFunction(Function&& function)
        : m_callable(std::make_unique<Callable<std::decay_t<Function>>>(
              std::forward<Function>(function))) {}
    ...
};

• Move-only. The copy constructor is = delete, the move is defaulted. A std::function copies; a UniqueFunction cannot, which is exactly the guarantee you want when a closure owns a resource (a buffer, a fence).
• std::decay_t<Function> strips references and const from the deduced type so the stored member has a concrete, plain type.
• std::forward re-applies the argument's original value category — lvalue stays an lvalue, rvalue stays an rvalue — so nothing is copied unnecessarily. std::move is the "I am done with this" cast; std::forward is the "pass it along as it came" cast.

Distinguish two meanings of &&. A parameter such as UniqueFunction<void>&& is an ordinary rvalue reference: it accepts an rvalue, and the function may move from it. In a deduced function template, T&& with a cv-unqualified template parameter is a forwarding reference: it accepts lvalues as well as rvalues. The constructor above uses that second form. A named variable is an lvalue expression even if its type is an rvalue reference; std::forward<T> restores the caller's value category. Neither && nor std::move alone performs an ownership transfer. See the language rules for forwarding-reference deduction and the runnable example below.

RAII — the object owns the resource

There is no garbage collector. A resource (memory, a Vulkan handle, a file) is owned by an object whose destructor releases it. std::unique_ptr is the default owner; std::shared_ptr is used when ownership genuinely must be shared.

auto& bucket = m_first_level[FirstLevelIndex(page)];
if (bucket == nullptr) {
    bucket = std::make_unique<Bucket>();   // allocated lazily, freed by the table's destructor
    ++m_allocated_buckets;
}

And here is the deliberate use of shared_ptr, from the event-queue code (also covered in HLE libraries): a queue can be destroyed while another thread is blocked in it, so it is pinned with a shared reference for the duration of the operation:

using KernelEqueueRef = std::shared_ptr<KernelEqueuePrivate>;
[[nodiscard]] KernelEqueueRef KernelPinEqueue(KernelEqueue eq);

RAII ties cleanup to an owning object's lifetime. That owner can be a local variable, a member or a dynamically allocated object. unique_ptr expresses exclusive ownership; several shared_ptr handles can share ownership until the final strong owner releases the managed object. Returning a unique_ptr gives the caller an exclusive owning handle; returning a shared_ptr may share ownership with handles that already exist. Follow the actual handle lifetimes, including deferred work and ownership cycles, rather than assuming closing one stack scope releases every resource.

Casts — four kinds, one habit

These cast spellings recur in this tree:

The one habit to build: reinterpret_cast is a promise with no runtime check. A static_assert(sizeof(...)) checks size only. It does not prove alignment, offsets, object lifetime, aliasing validity or that an address is mapped. When you see one, ask: what fixed layout is being relied on, and where is the assert?

Guest addresses are just integers

This is the single most important mental model for the codebase, and it is not a C++ feature — it is how C++ is used here. The game's memory lives in a 48-bit guest address space that the emulator lays out itself. Through most of the code, a guest address is an ordinary integer:

void     WriteBacking(uint64_t vaddr, const void* data, uint64_t size) noexcept;
void     InvalidateMemory(uint64_t vaddr, uint64_t size);
int      KYTY_SYSV_ABI KernelMprotect(const void* addr, size_t len, int prot);
uint64_t AllocateProgramMemory(uint64_t search_addr, uint64_t size, ...);

A real host pointer appears only at the boundary — when something must be executed or dereferenced. There the two worlds meet through reinterpret_cast:

auto* func = reinterpret_cast<entry_func_t>(addr);   // guest address → host function pointer
const auto aligned_stack_top =
    reinterpret_cast<uintptr_t>(stack_top) & ~static_cast<uintptr_t>(0x0f);

So the same eight bytes are a number in one function and a pointer in the next. For each vaddr or uint64_t argument, establish whether it represents a guest virtual address, host address, offset or plain integer. Guest mappings still occupy the host process; the integer type alone does not prove the domain.

Raw memory and fixed layouts

An emulator constantly reinterprets bytes, so the tree is disciplined about layout. Four tools come up over and over:

1. #pragma pack(1) — turns off padding. The compiler inserts alignment padding between struct members; when the struct must mirror a file format or a wire layout, that padding is poison. src/loader/jit.h wraps its machine-code structs in #pragma pack(1), and vaContext.h does the same for its register-save area.

#pragma pack(1)

struct VaList {
    uint32_t gp_offset;
    uint32_t fp_offset;
    void*    overflow_arg_area;
    void*    reg_save_area;
};

#pragma pack()

2. Bitfields — flags packed into a single word by declaring a bit width:

struct VirtualQueryInfo {
    ...
    uint32_t is_flexible  : 1;
    uint32_t is_direct    : 1;
    uint32_t is_stack     : 1;
    uint32_t is_pooled    : 1;
    uint32_t is_committed : 1;
    uint32_t is_gpu_prt   : 1;
    uint32_t amm_usage    : 1;
    uint32_t reserved     : 1;
    char      name[KERNEL_MAXIMUM_NAME_LENGTH];
    uint8_t   gpu_mask_id;
    uint8_t   reserved2;
};

static_assert(sizeof(VirtualQueryInfo) == 72, "VirtualQueryInfo struct size is incorrect");

C++ bitfield allocation and ordering depend on the implementation. Guest and host code need not use the same compiler or ABI. An internal host representation can use bitfields under the project's compiler assumptions; guest-visible layouts must be checked against their actual binary contract. static_assert(sizeof(T) == N) proves only total size, not field offsets, bit positions or endianness. Use explicit masks/shifts when decoding format words, and verify required offsets and behavior separately.

3. Anonymous unions — several views of the same bytes, selected by a tag. The memory-pool batch entry is one 32-byte record whose meaning depends on op:

struct KernelMemoryPoolBatchEntry {
    uint32_t op;
    uint32_t flags;
    union {
        struct { void* addr; uint64_t len; uint8_t prot; uint8_t type; } commit;
        struct { void* addr; uint64_t len; } decommit;
        struct { void* dst;  void* src;  uint64_t len; } move;
        ...
        uintptr_t padding[3];
    };
};

4. offsetof — the byte offset of a member within a struct. vaContext.h uses it to build a hand-rolled variadic-argument reader by offset arithmetic on the register save area.

(ctx).va_list.gp_offset         = offsetof(VaRegSave, gp);
(ctx).va_list.fp_offset         = offsetof(VaRegSave, fp);

Follow std::vector, direct magic_enum calls, std::filesystem::path and common/alignment.h in current code. Profiler macros create native tracy::ScopedZone objects.

Attributes — messages to the compiler

Attributes are contracts with the compiler, not runtime features. The ones that recur:

The preprocessor as a code generator

Modern C++ avoids macros, but this codebase uses them deliberately in three places — and you must read them to read the libraries:

1. Special-member boilerplate. Deleted copy/move constructors for a whole class in one line:

#define KYTY_CLASS_NO_COPY(name)                                                       \
public:                                                                                 \
    name(const name&)                = delete;                                         \
    name& operator=(const name&)     = delete;                                         \
    name(name&&) noexcept            = delete;                                         \
    name& operator=(name&&) noexcept = delete;

2. The HLE registration DSL. The whole of src/libs/ is registered with a handful of macros (covered in HLE libraries and animated below). Notice the # operator in LIB_ADD — it stringifies its argument at compile time, turning a function name into a log label with no reflection machinery:

#define LIB_ADD(n, f, t)                                                       \
    {                                                                          \
        Loader::SymbolResolve sr {};                                           \
        sr.name  = n;  sr.library = g_library;  sr.module = g_module;          \
        ...
        auto        func     = reinterpret_cast<uint64_t>(f);                  \
        const char* dbg_name = "" #f;        // "function_name" as a string \
        s->Add(sr, func, dbg_name);                                            \
    }

#define LIB_FUNC(n, f) LIB_ADD(n, f, Loader::SymbolType::Func)

3. ABI shims that must be spelled identically at every call site — VA_ARGS expands to the System V argument list, VA_CONTEXT to the code that captures it into a struct.

Reading a macro: expand it in your head, pasting the arguments into the body. The \ at line ends just means "this macro continues on the next line". __func__, used by PRINT_NAME(), names a predefined local character array containing the current function name. __FUNCTION__ is a compiler extension, not a template.

And the thread_local in LIB_NAME is worth calling out: each translation unit gets its own per-thread flag, which is how PRINT_NAME_ENABLE(true) can turn on tracing for one module on one thread without flooding the log from everywhere else.

The modern STL you will meet

Familiarity with a handful of headers covers most of the tree:

Coming from TypeScript / JavaScript