1 of 40

NativeDB · Documentation

Home

Space to store and share documentation of RTTI definitions.

This space stores documentation and is used to show it when browsing RTTI dump using NativeDB.

If you have an issue or feedback to share, come and talk about it on NativeDB@wiki channel.

If you want to contribute, please go to the next guide:

Contributing

This guide will give you a tour of everything you need to know to document the codebase of NativeDB.

Use GitBook

This space is used to write and store documentation. It will synchronize the data in a GitHub repository. NativeDB get the documentation from this repository to show it when browsing the codebase.

GitHub Api limits free access to 60 requests per hour. It doesn't require you to login with a GitHub account from NativeDB. It should be good enough for now.

If you never used GitBook before, you'll see that it is easy to use after learning some basics. to find your way around.

NativeDB provides buttons to quickly open GitBook in the right place:

NativeDB and GitBook

NativeDB expects a custom format and structure to get the data from GitBook, and to show it as beautifully as possible. You first need to learn a few rules, you can start with . It will also explain some guidelines on what to write or not when documenting.

Now that you made a change request, wrote some documentation, you can request a review. An administrator will check it, and if it is alright, merge your change request.

NativeDB will store the documentation in your browser as a cache. It helps improve performance and it reduces the usage of the network's bandwidth. It will only refresh the list of documented classes every 10 minutes (to see if there are changes to update locally). If NativeDB is already open, it will not show your last merged change request. You can wait up to 10 minutes or hit F5 to refresh your tab.

Thank you for your contributions!

If you get lost, If you think a guide lack information, If you think a guide is not clear enough, If you have any other feedback to share,

Please do reach us on Discord in the channel.

Structure

This guide explains the structure to follow when writing documentation for NativeDB.

One sub-page = one class

One sub-page = one struct

Sub-page of a class or a struct must be within page "CLASSES".

Order sub-pages alphabetically (from A to Z).

It is useful to quickly navigate between classes and to add new classes.

Class / Struct

You have to follow a small set of rules to write documentation about a class. The format described below is required to show the documentation in NativeDB.

A minimal example shows you how it should look like with Markdown, at the .

Setup page

Option "Page description" must be turned off in "Page options". You can find the feature when moving your mouse over the title of the page.

Title of the page must be the native name of the class. You can configure code syntax in NativeDB with option Pseudocode · Legacy to only show native names.

DO write vehicleBaseObject

DON'T write VehicleObject

Add a description

Add header "Description" using block "Heading 1".

DO write Description

DON'T write anything else, like descriptionS

After this header, you can add content (like a paragraph) to describe useful knowledge about the class. It will be visible like this in NativeDB:

Add functions

Add header "Functions" using block "Heading 1", if it doesn't exist already. You can then add functions after this header, as described below.

DO write Functions

DON'T write anything else, like Methods

Add a function using block "Heading 3". This header must be the signature of the function using the Pseudocode · Legacy code syntax.

If the signature of the function is not valid, your change request will not be merged.

You should use the feature provided by NativeDB to quickly copy the signature of a function in your clipboard. You can do so like this:

As an example with the function FindEntityById, it will look like this in your clipboard, ready to paste in GitBook:

Like with the description, you can then add content below the header of the function to describe it.

You don't have to write both sections (Description and Functions) when creating a new class. You need to at least add one of the two sections, be it Description or Functions.

When present, the section Description must be at the very top of the page.

Minimal example

You're ready to go on with the next guide:

Format and syntax

This guide explains what syntax you can use to format the documentation for NativeDB.

🟢 fully supported

🟠 partially supported

🔴 not supported

Blocks

Markdown

Description

Guidelines

This guide describes how documentation should be written. It also explains what should be documented or not, and why.

Introduction

The goal of this documentation is to share acquired knowledge about the codebase. It is not useful to document every single class and functions of this entire codebase.

Guidelines below are not hard rules that you must absolutely and always follow. The purpose is to give you (and contributors) a common ground to start from.

Explicit

One big rule is to add documentation when a class / a function is not explicit.

For example, the name of the class is not clear for someone who only played the game. In this case it is useful to add a sentence describing that Prevention means NCPD / the police.

DO add documentation to describe a behavior that is not already explicit.

DON'T add documentation about a class like , only to say "Class of the player".

DON'T add documentation about a function like , only to say "Return true when player is moving, false otherwise".

Keep it short

One phrase, one idea.

Reading is hard, keep it as short as possible. Below are patterns you can reuse to structure your comment:

Explain behavior

When a general description is somehow required and useful to provide context.

Pattern

Short description (up to 3 phrases).
Elaborate description (optional, when short description is not enough to fit knowledge).
Provide related resources / references (optional, when related and newcomers are not aware of it).

Example

Explain arguments

When behavior is already explicit, but an argument requires a description and more information like a default value, , etc.

Pattern

Short description (optional).
Argument with description and optionally the default value / a list of known values.

Example

Patterns above are propositions. It is easier as a reader to see and read documentation when it uses the same format everywhere. It might take a bit of an effort to get used to it as a writer.

Avoid code

This documentation is not about showing how to use a snippet of code: be it in Redscript, Lua or else. In this spirit, writing code in the documentation should be avoided. If it is deemed really useful, it should be as short as possible.

is already present to share knowledge about the code and scripting in general. You should share your findings in this space, not in this documentation.

Game vocabulary

More than often, people played the game and knows about the vocabulary it uses. It is preferable to use game's vocabulary to be on the same page.

For example, it is preferred to tell Prevention is about NCPD. This way, when you document other parts of the game related to Prevention, you can use the keyword NCPD. Others will understand what you're talking about.

As another example, you can write V when talking about the . It should be explicit for anyone, and is shorter to write than the player.

List known data

A function might need some kind of predefined data as arguments. Think about the CName type, it is a string-like type but values are not listed like enums. We don't know about them. In this case, a modder will have to dig and search what values the function accepts as a CName.

If you know all or even only one valid value, you should list them when documenting the function. This way, others know what data to use when they need to call this function too.

If the list of values is very big, use a link instead to reference some Sheet-like document containing all known values.

If the list of values is accessible using WolvenKit, add a note about it and provide the path where to look for the data.

Optional argument

An argument of a function is optional when marked with the opt prefix. It can be helpful to describe what default value is used. It can look like this:

CDPR only

In the codebase, you can find features that are not related to the gameplay, saves, the world, etc. For example, you should not care nor mess around with the .

In this case, you can add the comment "CDPR only". It is short and explicit enough to tell other modders:

There is nothing to see for modding purpose.

Conclusion

After reading this, you should better grasp what you can document and how. Don't hesitate to go through the current documentation. It can be helpful to see how other parts are already documented, to get more familiar with these guidelines.

Contributors

We welcome contributions, even tiny one, by anyone who wants to share knowledge with NativeDB.

You can leave a trace of your passage by adding your username below (Discord, Nexus or GitHub).

In alphabetical order, many thanks to:

manavortex
psiberx
Rayshader
rfuzzo
RollermineC
roms1383
Seijax
void*

GLOBALS

GetGameInstance() -> ScriptGameInstance

When Codeware is installed, you can use this function without issues. Otherwise, you may need to get [GameInstance] through other functions like [GameObject.GetGame] for example.

This function will only work when the game engine is initialized, meaning a [GameInstance] do exists.

FTLog(value: script_ref:String) -> Void

Use this function to write in logs, along with [FTLogWarning] and [FTLogError].

See for more about logging.

LogChannel() -> Void

See [FTLog] instead.

CLASSES

AIVehicleJoinTrafficCommand

Description

Cause the vehicle to join traffic and be immune to bumping. Useful in scripted scenes to prevent unexpected outcomes.

Use [vehicleJoinTrafficVehicleEvent] instead if you want the vehicle to behave like normal traffic.

EngineTime

Description

Time is in seconds when converted to a [Float].

entEntity

Description

An Entity is essentially a "thing" in the game world. This can be a player character, NPC, vehicle, or an object like a weapon or a door. Each entity has specific attributes, like health, position, and abilities, that define how it behaves and interacts with the environment.

Components: these are smaller parts that make up an entity, such as physics, animations, and behaviors. Components are what give an entity its abilities, like moving, interacting, or taking damage.

entIComponent

Description

Components in the game define the functionality of various objects and NPCs, such as physics, animations, interactions, and more. IComponent serves as a base class for all the specific components that can be attached to entities.

Modularity: components can be thought of as modules that add specific functionality to an entity. For example, you could add a physics component to give an object physical interactions with the environment or an AI component to allow an NPC to make decisions.
Reuse: since components are reusable, you can apply the same component to different entities. This makes it easier to add consistent behavior across various objects or NPCs.
Separation of Concerns: each component is responsible for handling a specific aspect of an entity. This makes it easier to focus on one feature at a time (such as movement, interaction, or combat behavior).

Functions

GetEntity() -> whandle:entEntity

Retrieve entity owner.

gameBlackboardSystem

Description

Blackboard is a kind of shared data storage and a framework to access/notify/listen to the data in the storage. Similar to a real blackboard, [GameObject]s put their data on the board ([IBlackboard]). Other objects can observe, react to and update the data.

Blackboard uses a key-value pattern to store data. Keys are defined through a [BlackboardDefinition]. You can know what keys (ids) a [IBlackboard] is using with its corresponding [BlackboardDefinition]. A list of known definitions can be found in [AllBlackboardDefinitions].

Functions

gameDelayID

Description

Use with [DelaySystem].

When undefined, a DelayID is equal to [GetInvalidDelayID].

gameDelaySystem

Description

Allows to schedule callbacks, events or system requests in various ways. Time / delay is expressed in seconds.

callback is triggered only once, but nothing prevents from rescheduling it manually at your convenience.

gameDelaySystemScriptedDelayCallbackWrapper

Description

Allows creating custom callbacks to use in-game with [DelaySystem].

If you're looking to trigger callbacks outside of game sessions, see wiki of Codeware for custom events.

Functions

Call() -> Void

Method which gets automatically called after delay, see [DelayCallback] and [DelaySystem.DelayCallbackNextFrame].

gameFxInstance

Functions

BreakLoop() -> Void

Stops emitting new particles. This is a smooth way to stop your effect's animation.

Kill() -> Void

Force the effect to stop right away.

UpdateTransform(transform: WorldTransform) -> Void

Change position and orientation of this effect in the world.

gameFxSystem

Description

This system allows you to spawn (particle) effects in the world. It should be able to spawn any [FxResource]. You can find a list of effects with WolvenKit in the AssetBrowser by filtering files with .effect extension.

Functions

SpawnEffect(resource: gameFxResource, transform: WorldTransform, opt ignoreTimeDilation: Bool) -> handle:gameFxInstance

Create a new effect at transform position in the world, based on a resource (your effect). You need to keep a reference of the returned [FxInstance] to later control and stop your effect.

See these snippets of code for and for to create a [FxResource].

gameGameAudioSystem

Description

Responsible for managing all audio-related functionality within the game. This system controls everything from background music and sound effects to character dialogue and environmental sounds.

Game sounds can be browsed and listened to on .

Sounds can be replaced with , with predefined .

If you need more control over how sounds can be played in-game, you might want to consider

gameIStatPoolsListener

Description

DON'T directly inherit this class to create your own listener. Game will crash to desktop if you try. You must use [ScriptStatPoolsListener] instead.

gamemappinsMappinSystem

Description

You can get a list of [IMappin], see the function provided by .

gamemountingMountingRelationship

Description

[this.otherObject] is not imported in script-side. You must use [IMountingFacility.RelationshipGetOtherObject] to get this property.

gameObject

Description

A GameObject is any in-game item or structure that the player or NPCs can interact with. This includes things like weapons, doors, vending machines, lootable containers, and even some environmental elements.

Functions

RegisterInputListener(listener: handle:IScriptable, opt name: CName) -> Void

name (of action) is allowed but using known object (e.g. [PlayerPuppet]) as listener is a source of potential issues. Mods should always declare and use a custom listener object, like in .

gameScriptableSystem

Description

Only available in-game, and re-created on each load.

See Codeware ScriptableService if you need to add logic outside of game sessions.

Functions

WasRestored() -> Bool

Whether session was restored (e.g. on save load), or not (e.g. on new game).

IsSavingLocked() -> Bool

Whether saving is currently disabled or not (e.g. during combat).

OnAttach() -> Void

Automatically called when attached to game session (e.g. on save load).

OnDetach() -> Void

Automatically called when detached from game session (e.g. on exit to main menu).

OnRestored(saveVersion: Int32, gameVersion: Int32) -> Void

Automatically called when restoring game session (e.g. on save load).

gameStatPoolsSystem

Functions

RequestRegisteringListener(objID: gameStatsObjectID, statPoolType: gamedataStatPoolType, listener: handle:gameIStatPoolsListener) -> Void

You can make your own listener by creating a class inheriting [ScriptStatPoolsListener]. You can use [this.RequestUnregisteringListener] when you need to remove your listener.

gameScriptableSystemRequest

Description

Allows triggering callbacks on [ScriptableSystem].

Prefer [DelayCallback] whenever possible.

More info and code snippets there.

Functions

Cancel() -> Void

Cancel currently running request.

gameTargetSearchQuery

Description

Used by functions of [TargetingSystem], to specify the parameters for searches of targets.

[this.testedSet] decides the shape of the area of the search (in the limits of [this.maxDistance]). [TargetingSet.Frustum] covers the whole cone of vision of the instigator. [TargetingSet.Visible] and [TargetingSet.ClearlyVisible] additionally require differing degrees of line-of-sight. [TargetingSet.Complete] covers a sphere around the instigator.
[this.searchFilter] identifies the nature of the objects that will qualify for the search. See REDmod script resources for examples of currently used filters, like [TSF_NPC].

gameTimeSystem

Description

Use with everything time-based:

real time

gameTransactionSystem

Functions

GiveMoney(target: handle:gameObject, amount: Int32, currency: CName) -> Bool

Known currency values: n"money".

RemoveMoney(obj: handle:gameObject, amount: Int32, currency: CName) -> Bool

Known currency values: n"money".

TransferMoney(source: handle:gameObject, target: handle:gameObject, amount: Int32, currency: CName) -> Bool

Known currency values: n"money".

inkScriptHashMap

Functions

Set(key: Uint64, value: handle:IScriptable) -> Void

Update value of entry at key, when an entry already exists. You must use [this.Insert] instead, when you want to add an entry for the first time.

inkTextWidget

Functions

SetFontFamily(fontFamilyPath: String, opt fontStyle: CName) -> Void

Known relative paths for fontFamilyPath

inkWidget

Description

See of Codeware to learn more about creating a UI. You should install too. It provides a powerful InkInspector tool to help you design a UI while in-game.

IScriptable

Functions

IsA(className: CName) -> Bool

className must be the native name (Pseudocode). For example, you must use n"entEntity" instead of n"Entity".

See also to use a straightforward syntax.

NPCPuppet

Description

Represents non-player characters (NPCs) in the game.

These are the characters that the player interacts with but doesn't directly control, such as enemies, civilians, vendors, and allies.

AI Behaviors: contains the logic for how NPCs think and act. This includes things like combat AI (how an enemy attacks, seeks cover, or flees), daily routines (what civilians do during the day), and response behaviors (like reacting to gunfire or the player's presence).
Factions: NPCs can belong to factions (e.g., gangs or corporate groups), and this affects how they interact with other factions and the player. You can adjust faction relationships, which influences whether NPCs are hostile, friendly, or neutral.

redEvent

Description

Dispatched throughout game session to trigger gameplay logic, for various purposes:

combat
traffic
...

Event can be dispatched in-game on instances of class inheriting from [Entity].

More info and code snippets .

If you're looking to dispatch events outside of game sessions, see for custom events.

redResourceReferenceScriptToken

Description

See for more about ResRef.

ScriptGameInstance

Description

Main entry-point to get systems for gameplay / environment / etc.

See the global function [GetGameInstance] which explains how to get a `GameInstance`.

Functions

GetAchievementSystem(self: ScriptGameInstance) -> handle:gameAchievementSystem

CDPR only.

GetDelaySystem(self: ScriptGameInstance) -> handle:gameDelaySystem

Get system used to execute callback functions after a delay. It runs functions asynchronously in game loop.

GetFxSystem(self: ScriptGameInstance) -> handle:gameFxSystem

Get system used to spawn particle effects in the world.

GetSimTime(self: ScriptGameInstance) -> EngineTime

Get elapsed time since the simulation started. Time is reset when navigating between menu and in-game scenes. Time is paused when game is paused (e.g. inventory menu is open).

GetTelemetrySystem(self: ScriptGameInstance) -> handle:gameTelemetryTelemetrySystem

CDPR only.

GetTeleportationFacility(self: ScriptGameInstance) -> handle:gameTeleportationFacility

Get system used to teleport a [GameObject] to [Vector4] coordinates or to a [NodeRef].

GetTimeSystem(self: ScriptGameInstance) -> handle:gameTimeSystem

Get system used to change game time, including time dilation.

GetVehicleSystem(self: ScriptGameInstance) -> handle:gameVehicleSystem

Get system used to summon vehicles and unlock vehicles in V's garage.

See also [VehicleObject], [VehicleComponent] and [vehicleController] to access more vehicle behaviours.

vehicleBaseObject

Functions

GetCurrentSpeed() -> Float

Value is meaningless as-is. You can convert the value to KPH or MPH by using the code from script car_hud.

vehicleVehicleBumpEvent

Description

Event is only triggered when a vehicle collides with another vehicle.

WorldWidgetComponent

Description

This class is named worlduiWidgetComponent when scripting.

NativeDB · Documentation

Home

Contributing

hashtagUse GitBook

hashtagNativeDB and GitBook

Structure

hashtagClass / Struct

hashtagSetup page

hashtagAdd a description

hashtagAdd functions

hashtagMinimal example

Format and syntax

Guidelines

hashtagIntroduction

hashtagExplicit

hashtagKeep it short

hashtagExplain behavior

hashtagPattern

hashtagExample

hashtagExplain arguments

hashtagPattern

hashtagExample

hashtagAvoid code

hashtagGame vocabulary

hashtagList known data

hashtagOptional argument

hashtagCDPR only

hashtagConclusion

Contributors

GLOBALS

hashtagGetGameInstance() -> ScriptGameInstance

hashtagFTLog(value: script_ref:String) -> Void

hashtagLogChannel() -> Void

CLASSES

AIVehicleJoinTrafficCommand

hashtagDescription

EngineTime

hashtagDescription

entEntity

hashtagDescription

entIComponent

hashtagDescription

hashtagFunctions

hashtagGetEntity() -> whandle:entEntity

gameBlackboardSystem

hashtagDescription

hashtagFunctions

gameDelayID

hashtagDescription

gameDelaySystem

hashtagDescription

gameDelaySystemScriptedDelayCallbackWrapper

hashtagDescription

hashtagFunctions

hashtagCall() -> Void

gameFxInstance

hashtagFunctions

hashtagBreakLoop() -> Void

hashtagKill() -> Void

hashtagUpdateTransform(transform: WorldTransform) -> Void

gameFxSystem

hashtagDescription

hashtagFunctions

hashtagSpawnEffect(resource: gameFxResource, transform: WorldTransform, opt ignoreTimeDilation: Bool) -> handle:gameFxInstance

gameGameAudioSystem

hashtagDescription

gameIStatPoolsListener

hashtagDescription

gamemappinsMappinSystem

hashtagDescription

gamemountingMountingRelationship

hashtagDescription

gameObject

hashtagDescription

hashtagFunctions

hashtagRegisterInputListener(listener: handle:IScriptable, opt name: CName) -> Void

gameScriptableSystem

hashtagDescription

hashtagFunctions

hashtagWasRestored() -> Bool

Use GitBook

NativeDB and GitBook

Class / Struct

Setup page

Add a description

Add functions

Minimal example

Introduction

Explicit

Keep it short

Explain behavior

Pattern

Example

Explain arguments

Pattern

Example

Avoid code

Game vocabulary

List known data

Optional argument

CDPR only

Conclusion

GetGameInstance() -> ScriptGameInstance

FTLog(value: script_ref:String) -> Void

LogChannel() -> Void

Description

Description

Description

Description

Functions

GetEntity() -> whandle:entEntity

Description

Functions

Description

Description

Description

Functions

Call() -> Void

Functions

BreakLoop() -> Void

Kill() -> Void

UpdateTransform(transform: WorldTransform) -> Void

Description

Functions

SpawnEffect(resource: gameFxResource, transform: WorldTransform, opt ignoreTimeDilation: Bool) -> handle:gameFxInstance

Description

Description

Description

Description

Description

Functions

RegisterInputListener(listener: handle:IScriptable, opt name: CName) -> Void

Description

Functions

WasRestored() -> Bool

IsSavingLocked() -> Bool

OnAttach() -> Void

OnDetach() -> Void

OnRestored(saveVersion: Int32, gameVersion: Int32) -> Void

Functions

RequestRegisteringListener(objID: gameStatsObjectID, statPoolType: gamedataStatPoolType, listener: handle:gameIStatPoolsListener) -> Void

Description

Functions

Cancel() -> Void

Description

Description

Functions

GiveMoney(target: handle:gameObject, amount: Int32, currency: CName) -> Bool

RemoveMoney(obj: handle:gameObject, amount: Int32, currency: CName) -> Bool

TransferMoney(source: handle:gameObject, target: handle:gameObject, amount: Int32, currency: CName) -> Bool

Functions

Set(key: Uint64, value: handle:IScriptable) -> Void

Functions

SetFontFamily(fontFamilyPath: String, opt fontStyle: CName) -> Void

Description

Functions

IsA(className: CName) -> Bool

Description

Description

Description