API reference#

Camera helper tools for 2D tile-based projects.

tcod.camera.clamp_camera(screen, world, camera, justify=0.5)#

Clamp the camera to the screen/world shapes. Preventing the camera from leaving the world boundary.

Parameters:

  • screen (tuple[int, ...]) – The screen shape.

  • world (tuple[int, ...]) – The world shape.

  • camera (tuple[int, ...]) – The current camera position.

  • justify (float | tuple[float, ...]) –

    The justification to use when the world is smaller than the screen. Defaults to 0.5 which will center the world when it is smaller than the screen.

    A value of zero will move a world smaller to the screen to inner corner. One would do the same but to the opposite corner. You may also give a tuple with a value for each axis.

Returns:

The new camera position clamped using the given shapes and justification rules.

Like the other functions, this camera position still assumes that the screen offset is (0, 0). This means that no other code changes are necessary to add or remove this clamping effect. This also means that changing justify also requires no external changes.

Return type:

tuple[int, …]

tcod.camera.get_camera(screen, center, clamping=None)#

Return the translation position for the camera from the given center position, screen size, and clamping rule.

Parameters:

  • screen (tuple[int, ...]) – The screen shape.

  • center (tuple[int, ...]) – The world position which the camera will center on.

  • clamping (tuple[tuple[int, ...], float | tuple[float, ...]] | None) –

    The clamping rules, this is (world, justify) as if provided to clamp_camera. If clamping is None then this function only does the minimum of subtracting half the screen size to get the camera position.

    world is the world shape. justify can be (0.5, 0.5) to center the world when it’s smaller than the camera, or (0, 0) to place the world towards zero. This would be the upper-left corner with libtcod.

Returns:

The clamped camera position.

Return type:

tuple[int, …]

tcod.camera.get_chunked_slices(screen, chunk_shape, camera)#

Iterate over map chunks covered by the screen.

Parameters:
Yields:

(screen_slice, chunk_index, chunk_slice)

For the chunk at chunk_index it should be sliced with chunk_slice to match a screen sliced with screen_slice.

Return type:

Iterator[tuple[tuple[slice, …], tuple[int, …], tuple[slice, …]]]

Example:

CHUNK_SIZE: tuple[int, int]
screen: NDarray  # Screen array.
chunks: dict[tuple[int, int], NDarray]  # Mapping of chunked arrays.
camera: tuple[int, int]
for screen_slice, chunk_ij, chunk_slice in tcod.camera.get_chunked_slices(screen.shape, CHUNK_SIZE, camera):
    if chunk_ij in chunks:
        screen[screen_slice] = chunks[chunk_ij][chunk_slice]

>>> list(get_chunked_slices((10,10),(10,10),(0,0)))
[((slice(0, 10, None), slice(0, 10, None)), (0, 0), (slice(0, 10, None), slice(0, 10, None)))]
>>> list(get_chunked_slices((10,10),(10,10),(-5,-5)))
[((slice(0, 5, None), slice(0, 5, None)), (-1, -1), (slice(5, 10, None), slice(5, 10, None))), ((slice(0, 5, None), slice(5, 10, None)), (-1, 0), (slice(5, 10, None), slice(0, 5, None))), ((slice(5, 10, None), slice(0, 5, None)), (0, -1), (slice(0, 5, None), slice(5, 10, None))), ((slice(5, 10, None), slice(5, 10, None)), (0, 0), (slice(0, 5, None), slice(0, 5, None)))]
tcod.camera.get_slices(screen, world, camera)#

Return (screen_slices, world_slices) for the given parameters.

This function takes any number of dimensions. The screen, world, and camera tuples must be the same length.

Parameters:
Returns:

The (screen_slice, world_slice) slices which can be used to index arrays of the given shapes.

Arrays indexed with these slices will always result in the same shape. The slices will be narrower than the screen when the camera is partially out-of-bounds. The slices will be zero-width if the camera is entirely out-of-bounds.

Return type:

tuple[tuple[slice, …], tuple[slice, …]]

Example:

console: tcod.console.Console  # Libtcod console, C order.
player_ij: tuple[int, int]  # Player (y, x) position.
world: NDArray[Any]  # Array created with `dtype=tcod.console.rgb_graphic`, C order.

console.clear()  # Clear the console in case any areas are not covered by tcod.camera.get_slices.

# Get the camera position centered on the player.
camera_ij = tcod.camera.get_camera(console.rgb.shape, player_ij)

# Get the screen/world slices at the camera position.
screen_slice, world_slice = tcod.camera.get_slices(console.rgb, world, camera_ij)
console.rgb[screen_slice] = world[world_slice]  # Render world graphics.

# Render the player.
player_screen_y, player_screen_x = player_ij[0] - camera_ij[0], player_ij[1] - camera_ij[1]
console.print(player_screen_x, player_screen_y, "@")
tcod.camera.get_views(screen, world, camera)#

Return (screen_view, world_view) for the given parameters.

This function takes any number of dimensions. The screen, world, and camera tuples must be the same length.

Parameters:

  • screen (_ScreenArray) – The NumPy array for the screen.

  • world (_WorldArray) – The NumPy array for the world.

  • camera (tuple[int, ...]) – The camera position.

Returns:

The given arrays pre-sliced into (screen_view, world_view) views.

These will always be the same shape. They will be sliced into a zero-width views once the camera is far enough out-of-bounds.

Convenient when you only have one screen and one world array to work with, otherwise you should call get_slices instead.

Return type:

tuple[_ScreenArray, _WorldArray]