API Camera

Camera

from proleak import camera

Read the game camera; moving it, and riding a unit in first person, needs the actions capability (local games only).

Classes | Functions

Classes

Class	Description
CameraDict	The game camera as get gives it.
Pov	A unit view from pov or third_person.

# The game camera as get gives it.
class CameraDict(TypedDict)

A plain dict with these keys.

Key	Type	Description
x	float	Map x position.
y	float	Height.
z	float	Map z position.
yaw	float	The direction it faces, in degrees (Unity's convention: 0 looks along +z).
pitch	float	Degrees it looks down.
fov	float	Its vertical field of view, in degrees.

# A unit view from pov or third_person. Setting a property takes effect at
# the next frame.
class Pov

Details

from proleak import camera, ui

def from_afar(unit):
    view = camera.third_person(unit)
    view.distance = 12                  # from the next frame
    view.show_unit = False

ui.unit_menu.add("Follow from afar", from_afar)

Property	Type	Description
mode read-only	str	"first" or "third".
offset read-only	tuple[float, float, float]	First person: (right, up, forward) from the anchor, in the unit's frame.
look read-only	tuple[float, float] | None	First person: (horizontal, vertical) look ranges in degrees, or None when off.
pitch read-only	float	Degrees the camera looks down (negative: up).
distance read-only	float	Third person: how far the camera is from the unit.
yaw read-only	float | None	Third person: the direction the camera faces, or None until it is first placed.
show_unit read-only	bool	Whether the unit's model stays visible.
alive read-only	bool	False once the view has ended.
unit read-only	int	The id of the unit the camera rides now (the wave fighter, during a wave).
type read-only	str	The unit type of the unit the view was started on.
anchor read-only	str	"head" or "top": where the view is measured from.

Method	Returns	Description
end()	None	End the view and put the camera back; does nothing once it has ended.

# End the view and put the camera back; does nothing once it has ended.
def end() -> None

Functions

Function	Returns	Description
get()	CameraDict	Where the game camera is and where it looks.
set(x: float | None = None, y: float | None = None, z: float | None = None, yaw: float | None = None, pitch: float | None = None, fov: float | None = None)	None	Move or turn the camera; omitted values stay as they are.
focus_unit(unit_id: int)	None	Center the camera on a unit.
reset()	None	Return the camera to the game's default.
pov(unit: Unit | int, offset: tuple[float, float, float] = (0.0, 0.0, 0.0), pitch: float = 0.0, show_unit: bool = False, look: tuple[float, float] | None = None)	Pov	Ride unit in first person; returns a Pov.
third_person(unit: Unit | int, distance: float = 6.0, yaw: float | None = None, pitch: float = 25.0, show_unit: bool = True, orbit: bool = True)	Pov	Follow unit from behind and above; returns a Pov.

# Where the game camera is and where it looks.
def get() -> CameraDict

Details

from proleak import camera, chat

@chat.command("where")
def where(cmd):
    view = camera.get()
    cmd.reply(f"x {view['x']:.0f}, z {view['z']:.0f}, height {view['y']:.0f}")

---

# Move or turn the camera; omitted values stay as they are.
def set(
    x: float | None = None,
    y: float | None = None,
    z: float | None = None,
    yaw: float | None = None,
    pitch: float | None = None,
    fov: float | None = None,
) -> None

Details

Argument	Type	Default	Description
x	float | None	None	The map x to move to.
y	float | None	None	The height to move to.
z	float | None	None	The map z to move to.
yaw	float | None	None	The direction to face, in degrees (Unity's convention: 0 looks along +z).
pitch	float | None	None	How far to look down, in degrees.
fov	float | None	None	The vertical field of view, in degrees.

from proleak import camera, input

@input.key("F7")
def top_down(ev):
    camera.set(pitch=90, fov=40)

---

# Center the camera on a unit.
def focus_unit(unit_id: int) -> None

Details

Argument	Type	Default	Description
unit_id	int	required	The unit's id.

from proleak import camera, on

@on("king.died")
def look(ev):
    camera.focus_unit(ev.king)

---

# Return the camera to the game's default.
def reset() -> None

---

# Ride unit in first person; returns a Pov.
def pov(
    unit: Unit | int,
    offset: tuple[float, float, float] = (0.0, 0.0, 0.0),
    pitch: float = 0.0,
    show_unit: bool = False,
    look: tuple[float, float] | None = None,
) -> Pov

Details

The camera sits at the unit's head (or the top of its model when it has no head point), moved by offset, and looks where the unit faces, pitch degrees down. The unit's health bar is hidden while the view lasts, and ground rings lie flat. A placed fighter hidden during a wave is followed through the unit that fights for it. With look, the player looks around by dragging with the middle mouse button.

One plugin holds the view at a time: calling again (or calling third_person) from the same plugin moves the view to the new unit, from another plugin raises ValueError. The view ends with end, when its unit leaves the game, or when the plugin unloads, and the camera goes back to where it was.

Argument	Type	Default	Description
unit	Unit | int	required	The unit, as a Unit or its id.
offset	tuple[float, float, float]	(0.0, 0.0, 0.0)	Moves the camera from the unit's head, as (right, up, forward) in the unit's own frame and in world units.
pitch	float	0.0	How far the camera looks down from where the unit faces, in degrees.
show_unit	bool	False	Whether the unit's model stays visible.
look	tuple[float, float] | None	None	Lets the player look around within (horizontal, vertical) degrees, at most 180 each (90 is 45 each way, 0 turns an axis off). None: the view stays fixed.

from proleak import camera, input, world

view = None

@input.key("F8")
def ride(ev):
    global view
    if view is not None and view.alive:
        view.end()
        return
    you = world.player()
    picked = you.selected() if you else []
    if picked:
        view = camera.pov(picked[0], offset=(0, 0.5, 0), pitch=10, look=(90, 60))

---

# Follow unit from behind and above; returns a Pov.
def third_person(
    unit: Unit | int,
    distance: float = 6.0,
    yaw: float | None = None,
    pitch: float = 25.0,
    show_unit: bool = True,
    orbit: bool = True,
) -> Pov

Details

The camera looks at the unit's head (or the top of its model). With orbit, read the view's yaw, pitch and distance to keep where the player left it. The view is held and ends as pov describes.

Argument	Type	Default	Description
unit	Unit | int	required	The unit, as a Unit or its id.
distance	float	6.0	How far the camera is from the unit's head, in world units.
yaw	float | None	None	The direction the camera faces, in degrees (Unity's convention: 0 looks along +z). None: behind the unit.
pitch	float	25.0	How far the camera looks down, in degrees.
show_unit	bool	True	Whether the unit's model stays visible.
orbit	bool	True	Whether the player can turn the camera around the unit (middle mouse button) and move it closer or further (wheel).

from proleak import camera, ui

ui.unit_menu.add("Follow", lambda unit: camera.third_person(unit, distance=8, pitch=30))

---

Previous: Background tasks | Next: Chat