Repository navigation
API Game assets
| Import | from proleak import assets |
The game's assets as this player hears and sees them: sounds, music, models, the map, effects and lighting.
| Class | |
|---|---|
Sound |
A sound file of the plugin, from load_sound. |
Bundle |
A Unity asset bundle of the plugin, from load_bundle. |
Effect |
An effect playing, from play_effect. |
Doodad |
One decoration of the map (a tree, a rock, a building, a light), or a model a plugin placed. |
| Returns | Function | |
|---|---|---|
None |
register(*paths: str) |
Registers the game's sounds, models and effects this plugin uses, such as "Sounds/Effects/GoldCoins", "Models/Characters/Mech/Zeus" and "Particles/VFX/Environment/FallingSnow.pkfx". |
Sound |
load_sound(file: str) |
Loads a WAV or OGG file of the plugin's folder (at most 32 MB), such as "music/theme.ogg", while the plugin loads (in its module or on_load). |
Bundle |
load_bundle(file: str) |
Loads a Unity asset bundle of the plugin's folder (at most 256 MB), built for the game's Unity version (2022.3.76f1), while the plugin loads (in its module or on_load). |
None |
play_sound(sound: Sound | str, *, at: tuple[float, float] | None = None, unit: Unit | int | None = None) |
Plays a sound everywhere, at map point at ((x, z)), or from unit. |
Effect |
play_effect(path: str, x: float | None = None, z: float | None = None, *, unit: Unit | int | None = None, y: float | None = None, seconds: float = 0.0, scale: float = 1.0) |
Plays the game's effect at path (such as "Particles/VFX/Environment/FallingSnow.pkfx") for seconds (0: until stopped). |
None |
replace(path: str, source: Sound | str) |
Puts source in place of the game's sound or model at path, from the next time the game loads it. |
None |
replace_ui_sound(name: str, sound: Sound | str) |
Plays sound in place of a UI sound, by its name in sfx.names. |
None |
restore(path: str) |
Gives the game its own asset at path back; a path the plugin did not replace is ignored. |
None |
restore_ui_sound(name: str) |
Gives the game its own UI sound name back. |
list[str] |
changed() |
What this plugin changed: replaced paths, doodads, effects, the map and the lighting. |
list[str] |
loaded() |
The paths of the sounds and models the game has loaded since it started, sorted: the paths to replace. |
None |
add_music(sound: Sound) |
Adds sound to the music of each game, after the game's own tracks. |
None |
remove_music(sound: Sound) |
Takes sound out of the music of the games to come. |
None |
play_music(sound: Sound) |
Plays sound as the music now, until the game changes its music; it must be ready. |
None |
stop_music() |
Stops the music playing. |
list[Doodad] |
doodads(*, near: tuple[float, float] | None = None, radius: float | None = None) |
The map's decorations now, the placed models among them; empty while no map is loaded. |
Doodad |
doodad(path: str) |
The map's doodad at path; KeyError when the map has none there. |
Doodad |
place(model: str, x: float, z: float, *, y: float | None = None, turn: float = 0.0, scale: float = 1.0) |
Places a model at map point (x, z), and returns it. |
None |
swap_effect(path: str, to: str) |
Shows the game's effect to wherever the game starts the effect path, from then on. |
None |
restore_effect(path: str) |
The game shows its own effect at path again. |
None |
replace_map(model: str) |
Shows model in place of the map's ground and decorations, on every map load: a model of the game, or a model or scene (a name ending .unity) of a Bundle. |
None |
restore_map() |
The game's own map again. |
None |
set_lighting(theme: str | None = None, *, lock: bool = False, color: tuple[float, float, float] | None = None, intensity: float | None = None, ambient: tuple[float, float, float] | None = None) |
Sets the map's lighting. |
None |
reset_lighting() |
The game's own lighting again. |
A plugin plays the game's sounds and effects wherever it likes, places the game's models or its own (from a Unity asset bundle in its folder), puts its own sounds and models in place of the game's, moves, hides and resizes the map's decorations, shows a model in place of the whole map, and sets the lighting. The changes reach this player only.
What players buy (skins, monuments, and the models, effects and sounds that come with them) is a
cosmetic: a call that names one works on a local ProLeak server only, raises NotAllowedHere
elsewhere, and what it changed goes back to the game's own as the player leaves the local game.
What a plugin changes during a game goes back to the game's own as the player leaves that game,
and everything it changed goes back when the plugin unloads. A plugin registers the game's
assets it uses while it loads (register).
register(*paths: str) -> None
Registers the game's sounds, models and effects this plugin uses, such as
"Sounds/Effects/GoldCoins", "Models/Characters/Mech/Zeus" and
"Particles/VFX/Environment/FallingSnow.pkfx".
It works while the plugin loads (in its module or on_load). The game loads every registered
asset ahead, in the background, once it has started, so its first use costs nothing. A call
naming a game path the plugin did not register raises ValueError; the map's doodads, the
plugin's own sounds and bundle models need no registering. A mode registers the assets only it
uses with modes.mode's assets.
load_sound(file: str) -> Sound
Loads a WAV or OGG file of the plugin's folder (at most 32 MB), such as "music/theme.ogg",
while the plugin loads (in its module or on_load).
The sound loads in the background; whatever it is given to do waits for it.
load_bundle(file: str) -> Bundle
Loads a Unity asset bundle of the plugin's folder (at most 256 MB), built for the game's Unity
version (2022.3.76f1), while the plugin loads (in its module or on_load). It loads in the
background.
play_sound(sound: Sound | str, *, at: tuple[float, float] | None = None, unit: Unit | int | None = None) -> None
Plays a sound everywhere, at map point at ((x, z)), or from unit.
sound is a Sound or a path of the game's sounds, such as
"Sounds/Effects/GoldCoins".
play_effect(path: str, x: float | None = None, z: float | None = None, *, unit: Unit | int | None = None, y: float | None = None, seconds: float = 0.0, scale: float = 1.0) -> Effect
Plays the game's effect at path (such as "Particles/VFX/Environment/FallingSnow.pkfx")
for seconds (0: until stopped).
It plays at map point (x, z), on the ground or at height y; or on unit, following it (at
height y above its feet) and ending with it.
replace(path: str, source: Sound | str) -> None
Puts source in place of the game's sound or model at path, from the next time the game loads it.
path is a path of the game's assets, such as "Sounds/Music/Menu" or
"Models/Characters/Mech/APS". source is a Sound, a model of a
Bundle, or another path of the game's. A path another plugin
changed raises ValueError with its name.
replace_ui_sound(name: str, sound: Sound | str) -> None
Plays sound in place of a UI sound, by its name in sfx.names.
restore(path: str) -> None
Gives the game its own asset at path back; a path the plugin did not replace is ignored.
restore_ui_sound(name: str) -> None
Gives the game its own UI sound name back.
changed() -> list[str]
What this plugin changed: replaced paths, doodads, effects, the map and the lighting.
loaded() -> list[str]
The paths of the sounds and models the game has loaded since it started, sorted: the paths to replace.
add_music(sound: Sound) -> None
Adds sound to the music of each game, after the game's own tracks.
remove_music(sound: Sound) -> None
Takes sound out of the music of the games to come.
play_music(sound: Sound) -> None
Plays sound as the music now, until the game changes its music; it must be ready.
stop_music() -> None
Stops the music playing.
doodads(*, near: tuple[float, float] | None = None, radius: float | None = None) -> list[Doodad]
The map's decorations now, the placed models among them; empty while no map is loaded.
With near=(x, z) and radius, only those standing within radius of that map point (on
the ground plane) are listed. Without them, every group and model under the map's doodads is
listed (some 2500 on the Legion TD 2 map), which costs a good part of a handler's time budget:
ask for the area needed, keep a full list rather than asking again, and use
doodad for one whose path is known.
doodad(path: str) -> Doodad
The map's doodad at path; KeyError when the map has none there.
place(model: str, x: float, z: float, *, y: float | None = None, turn: float = 0.0, scale: float = 1.0) -> Doodad
Places a model at map point (x, z), and returns it.
model is a doodad of the map (its path), a model of the game (such as
"Models/Doodads/CrystalCoast/Lightshafts_Day" or "Models/Characters/Mech/APS"), or a model
of a Bundle.
swap_effect(path: str, to: str) -> None
Shows the game's effect to wherever the game starts the effect path, from then on.
restore_effect(path: str) -> None
The game shows its own effect at path again.
replace_map(model: str) -> None
Shows model in place of the map's ground and decorations, on every map load: a model of
the game, or a model or scene (a name ending .unity) of a Bundle.
Lanes, units and placing stay the game's.
restore_map() -> None
The game's own map again.
set_lighting(theme: str | None = None, *, lock: bool = False, color: tuple[float, float, float] | None = None, intensity: float | None = None, ambient: tuple[float, float, float] | None = None) -> None
Sets the map's lighting.
theme is the game's "day", "night" or "fade"; with lock=True it stays whatever theme
the game asks for (the game turns day and night with its phases). color and ambient are
(red, green, blue) from 0 to 1 for the main light and the ambient light, and intensity
the main light's, 0 to 10. What is left out stays the game's.
reset_lighting() -> None
The game's own lighting again.
A sound file of the plugin, from load_sound.
| Type | Property | |
|---|---|---|
str |
file |
The file's path in the plugin folder. |
str |
path read-only
|
Where the game finds the sound once ready: any call that takes a sound path takes it. |
str |
state read-only
|
"loading", "ready", or "failed: " and the reason. |
file: str
The file's path in the plugin folder.
path: str [read-only]
Where the game finds the sound once ready: any call that takes a sound path takes it.
state: str [read-only]
"loading", "ready", or "failed: " and the reason. A sound loads in the background.
A Unity asset bundle of the plugin, from load_bundle.
| Type | Property | |
|---|---|---|
str |
file |
The file's path in the plugin folder. |
str |
state read-only
|
"loading", "ready", or "failed: " and the reason. |
| Returns | Method | |
|---|---|---|
list[str] |
names() |
The assets and scenes the bundle holds, such as "assets/models/tower.prefab" and "assets/scenes/arena.unity"; empty while it loads. |
str |
model(name: str) |
The path of the bundle's model name (one of names), for place, replace and replace_map. |
file: str
The file's path in the plugin folder.
state: str [read-only]
"loading", "ready", or "failed: " and the reason.
names() -> list[str]
The assets and scenes the bundle holds, such as "assets/models/tower.prefab" and
"assets/scenes/arena.unity"; empty while it loads.
model(name: str) -> str
The path of the bundle's model name (one of names), for
place, replace and replace_map.
An effect playing, from play_effect.
| Type | Property | |
|---|---|---|
str |
path |
The effect's path. |
| Returns | Method | |
|---|---|---|
None |
stop() |
Ends the effect. |
path: str
The effect's path.
stop() -> None
Ends the effect.
One decoration of the map (a tree, a rock, a building, a light), or a model a plugin placed.
| Type | Property | |
|---|---|---|
str |
path |
Where it sits under the map's doodads, such as "Trees/Pine_03"; a placed model's id. |
float |
x |
Map x. |
float |
y |
Height. |
float |
z |
Map z. |
float |
turn |
Its turn in degrees. |
float |
scale |
Its size against its own. |
bool |
visible |
Whether it shows. |
str |
effect |
The effect it shows; empty for none. |
int |
children |
How many doodads sit directly under it: a group such as "DoodadsV1/_ROCKS" holds others (hiding it hides them all); 0 for a single model. |
str | None |
like |
For a placed model: the model it shows. |
| Returns | Method | |
|---|---|---|
None |
hide() |
It no longer shows. |
None |
show() |
It shows again. |
None |
move(x: float, z: float, y: float | None = None) |
It stands at map point (x, z), on the ground or at height y. |
None |
turn_to(degrees: float) |
It faces degrees round the vertical axis. |
None |
resize(scale: float) |
Its size against its own, above 0 and at most 10. |
None |
show_effect(path: str) |
Its effects show the game's effect at path (an empty path shows none). |
None |
reset() |
It looks as the game made it again; a placed model goes. |
From doodads and place. Changing a doodad holds it for this plugin until reset, or until the player leaves the game the change was made in.
path: str
Where it sits under the map's doodads, such as "Trees/Pine_03"; a placed model's id.
x: float
Map x.
y: float
Height.
z: float
Map z.
turn: float
Its turn in degrees.
scale: float
Its size against its own.
visible: bool
Whether it shows.
effect: str
The effect it shows; empty for none.
children: int
How many doodads sit directly under it: a group such as "DoodadsV1/_ROCKS" holds
others (hiding it hides them all); 0 for a single model.
like: str | None
For a placed model: the model it shows.
hide() -> None
It no longer shows.
show() -> None
It shows again.
move(x: float, z: float, y: float | None = None) -> None
It stands at map point (x, z), on the ground or at height y.
turn_to(degrees: float) -> None
It faces degrees round the vertical axis.
resize(scale: float) -> None
Its size against its own, above 0 and at most 10.
show_effect(path: str) -> None
Its effects show the game's effect at path (an empty path shows none).
reset() -> None
It looks as the game made it again; a placed model goes.
Using ProLeak
Features
Tutorial
- Your first plugin
- Plugin basics
- Handling events
- Plugin settings
- User interface
- Players, units and game data
- Purchases, signals and pings
- Chat, camera, input and more
- Game assets
- Game modes
- Game updates
- Publishing plugins
Reference