Dark Souls III

This module contains the game interface for Dark Souls III.

class soulsgym.games.darksouls3.DarkSoulsIII

Bases: Game

Dark Souls III game interface.

__init__()

Initialize the MemoryManipulator and the GameInput.

Note

The game has to run at initialization, otherwise the initialization of the MemoryManipulator will fail.

property img: ndarray

Get the current game image as numpy array.

Warning

If the game was paused (i.e. game_speed = 0) before the current `Game instance has been created, this method won’t return. The game needs to be unpaused at least once before invoking this method.

Images have a shape of [90, 160, 3] with RGB channels.

property img_resolution: tuple[int, int]

The game image resolution.

Note

This is NOT the game window resolution. The game window resolution is the resolution the game is rendered in. img_resolution is the resolution of the image returned by DarkSoulsIII.img(). Depending on the game window resolution, the image is either downscaled or upscaled.

Returns:

The game image resolution.

property window_resolution: tuple[int, int]

The game window resolution.

Note

This is NOT the image resolution. See DarkSoulsIII.img_resolution() for more details.

Returns:

The game window resolution.

property screen_mode: str

The game screen mode.

Returns:

The game screen mode. Either ‘window’ or ‘fullscreen’.

property player_hp: int

The player’s current hit points.

Returns:

The player’s current hit points.

property player_sp: int

The player’s current stamina points.

Returns:

The player’s current stamina points.

property player_max_hp: int

The player’s maximum hit points.

Returns:

The player’s maximum hit points.

property player_max_sp: int

The player’s maximum stamina points.

Returns:

The player’s maximum stamina points.

reset_player_hp()

Reset the player’s hit points to its current maximum.

reset_player_sp()

Reset the player’s stamina points to its current maximum.

property player_pose: ndarray

The player’s current pose.

Poses are the combination of position and rotation. In the case of game entities (e.g. the player or bosses) the rotation is given as a single angle in radians around the z axis.

Setting the player’s pose is more complex than just overwriting the pose values. The player might be killed if the teleported distance is interpreted as a fall. We save the player death game flag, disable player deaths and gravity, set the coordinates and restore the player death flag to its previous state. Gravity is always enabled after a teleport.

Warning

Pose modifications are particularly affected by race conditions!

Returns:

The current player pose as [x, y, z, a].

property player_animation: str

The player’s current animation name.

Note

The player animation cannot be overwritten.

Returns:

The player’s current animation name.

property player_animation_time: float

The player’s current animation duration.

Note

The player animation time cannot be overwritten.

Returns:

The player’s current animation time.

property player_animation_max_time: float

The player’s current animation maximum duration.

Note

The player animation max time cannot be overwritten.

Returns:

The player’s current animation maximum duration.

property allow_player_death: bool

Disable/enable player deaths ingame.

property player_stats: tuple[int]

The current player stats from the game.

The stats can be overwritten by a tuple of matching dimension (10) and order. Stats are ordered as follows: Soul Level, Vigor, Attunement, Endurance, Vitality, Strength, Dexterity, Intelligence, Faith, Luck.

Returns:

A tuple with all player attributes in the same order as in the game.

property player_frost_resistance: float

The player’s frostbite resistance relative to its maximum capacity.

Is 1 if no frostbite resistance is missing, else decreases from 1. to 0.

Returns:

The player’s frostbite resistance.

property player_frost_effect: float

The player’s remaining frostbite effect duration.

Is 0. if the player is not frostbitten, else decreases from 1. to 0.

Returns:

The player’s frostbite effect duration.

property iudex_flags: bool

Iudex boss fight flags.

True means the Iudex flags are set to “encountered”, “sword pulled out” and “not defeated”. In addition, the “Untended Graves” flag is set to False (0x0). All other configurations are False. When the flag is set to False, the “encountered”, “sword pulled out” and “defeated” flags are set to False. The “Untended Graves” flag remains untouched.

Note

Iudex Gundyr and Champion Gundyr share the exact same area in the game. Which level is loaded depends on the “Untended Graves” flag. If the flag is set to False, the “Cemetery of Ash” version of the level loads. If it is set to True (0xA), the “Untended Graves” version loads. The flag is set by the game whenever the player advances past Firelink Shrine. Warping from bonfires loads the correct level, but setting the last bonfire and respawning will not. Therefore, the “Untended Graves” flag has to be set to False when we want to spawn in “Cemetery of Ash”.

Note

The “Untended Graves” flag is known in the CheatEngine community as “ceremony” flag. Additional infos can be found in inuNorii’s warp script in the grand archives cheat table.

Returns:

True if all flags are correct, False otherwise.

property vordt_flags: bool

Vordt boss fight flags.

See DarkSoulsIII.iudex_flags for more details.

property iudex_hp: int

Iudex Gundyr’s HP.

property vordt_hp: int

Vordt of the Boreal Valley’s HP.

property iudex_max_hp: int

Iudex Gundyr’s maximum HP.

property vordt_max_hp: int

Vordt of the Boreal Valley’s maximum HP.

reset_boss_hp(boss_id: str)

Reset the current boss hit points.

Parameters:

boss_id – The boss ID.

property iudex_pose: ndarray

Iudex Gundyr’s pose.

property vordt_pose: ndarray

Vordt of the Boreal Valley’s pose.

property iudex_phase: int

Iudex Gundyr’s phase.

property vordt_phase: int

Vordt of the Boreal Valley’s phase.

property iudex_animation: str

Iudex Gundyr’s animation.

property vordt_animation: str

Vordt of the Boreal Valley’s animation.

property iudex_animation_time: float

Iudex Gundyr’s animation time.

property vordt_animation_time: float

Vordt of the Boreal Valley’s animation time.

property iudex_animation_max_time: float

Iudex Gundyr’s animation maximum time.

property vordt_animation_max_time: float

Vordt of the Boreal Valley’s animation maximum time.

property iudex_attacks: bool

Iudex Gundyr’s boss attacks flag.

property vordt_attacks: bool

Vordt of the Boreal Valley’s boss attacks flag.

property camera_pose: ndarray

Read the camera’s current position and rotation.

The camera orientation is specified as the normal of the camera plane. Since the plane never rotates around this normal the camera pose is fully specified by this 3D vector.

Returns:

The current camera rotation as normal vector and position as coordinates [x, y, z, nx, ny, nz].

property last_bonfire: str

The bonfire name the player has rested at last.

The bonfire name has to be in the bonfires dictionary.

Returns:

The bonfire name.

property allow_attacks: bool

Globally enable/disable attacks for all entities.

property allow_hits: bool

Globally enable/disable hits for all entities.

No hits is equivalent to all entities having unlimited iframes, i.e. they are unaffected by all attacks, staggers etc.

property allow_moves: bool

Globally enable/disable movement for all entities.

property allow_deaths: bool

Globally enable/disable deaths for all entities.

property allow_weapon_durability_dmg: bool

Globally enable/disable weapon durability damage for all entities.

reload()

Kill the player, clear the address cache and wait for the player to respawn.

property lock_on: bool

The player’s current lock on status.

Note

Lock on cannot be set.

Returns:

True if the player is currently locked on a target, else False.

property lock_on_bonus_range: float

The current maximum bonus lock on range.

Default lock on range is 15. We only report any additional lock on range. Similarly, setting this value to 0 will result in the default lock on range 15.

Returns:

The current maximum bonus lock on range.

property los_lock_on_deactivate_time: float

The current line of sight lock on deactivate time.

If the player looses line of sight for longer than this time period, the game will remove the camera lock. Default value is 2.

Returns:

The current line of sight lock on deactivate time.

property time: int

Ingame time.

Measured as the current game save play time in milliseconds.

Note

Also increases when global game speed is set to 0, but should not increase during lags.

Warning

Possibly overflows after 1193h of play time.

Returns:

The current game time.

static timed(tend: int, tstart: int) → float

Safe game time difference function.

If time has overflowed, uses 0 as best guess for tstart. Divides by 1000 to get the time difference in seconds.

Parameters:

• tend – End time.

• tstart – Start time.

Returns:

The time difference.

sleep(t: float)

Custom sleep function.

Guarantees the specified time has passed in ingame time.

Parameters:

t – Time interval in seconds.

property game_speed: float

The game loop speed.

Note

Setting this value to 0 will effectively pause the game. Default speed is 1.

Warning

The process slows down with game speeds lower than 1. Values close to 0 may cause windows to assume the process has frozen.

Warning

Values significantly higher than 1 (e.g. 5+) may not be achievable for the game loop. This is probably dependant on the available hardware.

Returns:

The game loop speed.

Raises:

ValueError – The game speed was set to negative values.

property gravity: bool

The current gravity activation status.

Returns:

True if gravity is active, else False.

property is_ingame: bool

Flag that checks if the player is currently loaded into the game.

Returns:

True if the player is ingame, else False.

pause()

Pause the game by setting the global speed to 0.

resume()

Resume the game by setting the global speed to 1.

clear_cache()

Clear the address cache of the memory manipulator.

Warning

The cache is invalidated on a player death and needs to be manually cleared. See MemoryManipulator.clear_cache() for detailed information.