From 80756a14446e1720d16bcd7114252113f5e47c63 Mon Sep 17 00:00:00 2001 From: Roman Trapeznikov Date: Tue, 22 Feb 2022 20:14:25 +0300 Subject: [PATCH] more stuff --- assets/src/ba_data/python/._ba_sources_hash | 2 +- assets/src/ba_data/python/_ba.py | 43 ++-- assets/src/ba_data/python/ba/_account.py | 2 +- assets/src/ba_data/python/ba/_achievement.py | 4 +- assets/src/ba_data/python/ba/_activity.py | 9 +- assets/src/ba_data/python/ba/_actor.py | 34 ++- assets/src/ba_data/python/ba/_ads.py | 2 +- assets/src/ba_data/python/ba/_app.py | 2 +- assets/src/ba_data/python/ba/_appconfig.py | 4 +- assets/src/ba_data/python/ba/_campaign.py | 2 +- assets/src/ba_data/python/ba/_collision.py | 4 +- assets/src/ba_data/python/ba/_coopgame.py | 2 +- assets/src/ba_data/python/ba/_coopsession.py | 12 +- assets/src/ba_data/python/ba/_dependency.py | 8 +- .../src/ba_data/python/ba/_dualteamsession.py | 2 +- assets/src/ba_data/python/ba/_error.py | 32 +-- .../ba_data/python/ba/_freeforallsession.py | 2 +- assets/src/ba_data/python/ba/_gameactivity.py | 2 +- assets/src/ba_data/python/ba/_gameresults.py | 4 +- assets/src/ba_data/python/ba/_gameutils.py | 14 +- assets/src/ba_data/python/ba/_general.py | 110 +++++----- assets/src/ba_data/python/ba/_keyboard.py | 2 +- assets/src/ba_data/python/ba/_language.py | 50 ++--- assets/src/ba_data/python/ba/_level.py | 2 +- assets/src/ba_data/python/ba/_map.py | 14 +- assets/src/ba_data/python/ba/_messages.py | 106 ++++------ assets/src/ba_data/python/ba/_meta.py | 2 +- .../ba_data/python/ba/_multiteamsession.py | 2 +- assets/src/ba_data/python/ba/_music.py | 12 +- assets/src/ba_data/python/ba/_nodeactor.py | 2 +- assets/src/ba_data/python/ba/_plugin.py | 6 +- assets/src/ba_data/python/ba/_powerup.py | 24 +-- assets/src/ba_data/python/ba/_score.py | 4 +- assets/src/ba_data/python/ba/_servermode.py | 2 +- assets/src/ba_data/python/ba/_session.py | 2 +- assets/src/ba_data/python/ba/_stats.py | 6 +- assets/src/ba_data/python/ba/_team.py | 39 ++-- assets/src/ba_data/python/ba/_teamgame.py | 2 +- assets/src/ba_data/python/ba/_ui.py | 2 +- assets/src/ba_data/python/bastd/actor/bomb.py | 200 +++++++++--------- assets/src/ba_data/python/bastd/actor/flag.py | 97 ++++----- .../ba_data/python/bastd/actor/playerspaz.py | 18 +- .../ba_data/python/bastd/actor/powerupbox.py | 122 ++++++----- .../src/ba_data/python/bastd/actor/spawner.py | 28 ++- assets/src/ba_data/python/bastd/actor/spaz.py | 10 +- .../src/ba_data/python/bastd/actor/spazbot.py | 40 ++-- .../ba_data/python/bastd/actor/spazfactory.py | 110 +++++----- assets/src/ba_data/python/bastd/ui/config.py | 34 ++- .../class/python_class_collide_model.cc | 2 +- .../python/class/python_class_context.cc | 4 +- .../python/class/python_class_data.cc | 2 +- .../python/class/python_class_material.cc | 18 +- .../python/class/python_class_node.cc | 6 +- .../class/python_class_session_player.cc | 2 +- .../python/class/python_class_sound.cc | 2 +- .../python/class/python_class_widget.cc | 2 +- .../python/methods/python_methods_app.cc | 2 +- .../python/methods/python_methods_system.cc | 4 +- 58 files changed, 589 insertions(+), 689 deletions(-) diff --git a/assets/src/ba_data/python/._ba_sources_hash b/assets/src/ba_data/python/._ba_sources_hash index 63f57868..48a48da1 100644 --- a/assets/src/ba_data/python/._ba_sources_hash +++ b/assets/src/ba_data/python/._ba_sources_hash @@ -1 +1 @@ -93799056966445196696254000169758935495 \ No newline at end of file +251300217209184493283326875275347381659 \ No newline at end of file diff --git a/assets/src/ba_data/python/_ba.py b/assets/src/ba_data/python/_ba.py index a5eed344..2048b45d 100644 --- a/assets/src/ba_data/python/_ba.py +++ b/assets/src/ba_data/python/_ba.py @@ -79,7 +79,7 @@ class CollideModel: Category: **Asset Classes** - Use ba.getcollidemodel to instantiate one. + Use ba.getcollidemodel() to instantiate one. """ pass @@ -89,7 +89,7 @@ class Context: Category: **General Utility Classes** - Many operations such as ba.newnode or ba.gettexture operate + Many operations such as ba.newnode() or ba.gettexture() operate implicitly on the current context. Each ba.Activity has its own Context and objects within that activity (nodes, media, etc) can only interact with other objects from that context. @@ -104,7 +104,7 @@ class Context: When instantiating a ba.Context instance, a single `'source'` argument is passed, which can be one of the following strings/objects: - `'empty'`: + ###### `'empty'` > Gives an empty context; it can be handy to run code here to ensure it does no loading of media, creation of nodes, etc. @@ -199,7 +199,7 @@ class Data: Category: **Asset Classes** - Use ba.getdata to instantiate one. + Use ba.getdata() to instantiate one. """ def getvalue(self) -> Any: @@ -309,21 +309,21 @@ class InputDevice: class Material: """An entity applied to game objects to modify collision behavior. - Category: Gameplay Classes + Category: **Gameplay Classes** A material can affect physical characteristics, generate sounds, or trigger callback functions when collisions occur. - Materials are applied to ``'parts'``, which are groups of one or more + Materials are applied to 'parts', which are groups of one or more rigid bodies created as part of a ba.Node. Nodes can have any number of parts, each with its own set of materials. Generally materials are - specified as array attributes on the Node. The ``'spaz'`` node, for - example, has various attributes such as ``'materials'``, - ``'roller_materials'``, and ``'punch_materials'``, which correspond + specified as array attributes on the Node. The `spaz` node, for + example, has various attributes such as `materials`, + `roller_materials`, and `punch_materials`, which correspond to the various parts it creates. Use ba.Material to instantiate a blank material, and then use its - ba.Material.add_actions method to define what the material does. + ba.Material.add_actions() method to define what the material does. """ def __init__(self, label: str = None): @@ -399,7 +399,7 @@ class Material: `'at_connect'` or `'at_disconnect'`, and `message_obj` is the message object to send. This has the same effect as calling the node's - ba.Node.handlemessage method. + ba.Node.handlemessage() method. ###### `('modify_part_collision', attr, value)` > Changes some @@ -420,6 +420,7 @@ class Material: how springy the physical response is), `'damping'` (float value, how damped the physical response is), `'bounce'` (float value; how bouncy the physical response is). + ###### `('modify_node_collision', attr, value)` > Similar to `modify_part_collision`, but operates at a node-level. @@ -466,7 +467,6 @@ class Material: **Example 2:** send a ba.DieMessage to anything we touch, but cause no physical response. This should cause any ba.Actor to drop dead: - ```python >>> m = ba.Material() ... m.add_actions( ... actions=(('modify_part_collision', 'physical', False), @@ -474,7 +474,6 @@ class Material: ... ba.DieMessage()))) **Example 3:** play some sounds when we're contacting the ground: - ```python >>> m = ba.Material() ... m.add_actions( ... conditions=('they_have_material', @@ -499,7 +498,7 @@ class Model: class Node: """Reference to a Node; the low level building block of the game. - Category: Gameplay Classes + Category: **Gameplay Classes** At its core, a game is nothing more than a scene of Nodes with attributes getting interconnected or set over time. @@ -508,8 +507,8 @@ class Node: to a game node; *not* the node itself. This means a Node's lifecycle is completely independent of how many Python references to it exist. To explicitly add a new node to the game, use - ba.newnode, and to explicitly delete one, use ba.Node.delete. - ba.Node.exists can be used to determine if a Node still points to + ba.newnode(), and to explicitly delete one, use ba.Node.delete(). + ba.Node.exists() can be used to determine if a Node still points to a live node in the game. You can use ba.Node(None) to instantiate an invalid @@ -741,7 +740,7 @@ class SessionPlayer: Be aware that, like ba.Nodes, ba.SessionPlayer objects are 'weak' references under-the-hood; a player can leave the game at any point. For this reason, you should make judicious use of the - ba.SessionPlayer.exists method (or boolean operator) to ensure + ba.SessionPlayer.exists() method (or boolean operator) to ensure that a SessionPlayer is still present if retaining references to one for any length of time. """ @@ -858,7 +857,7 @@ class Sound: Category: **Asset Classes** - Use ba.getsound to instantiate one. + Use ba.getsound() to instantiate one. """ pass @@ -1044,7 +1043,7 @@ class Widget: This class represents a weak reference to a widget object in the internal C++ layer. Currently, functions such as - ba.buttonwidget must be used to instantiate or edit these. + ba.buttonwidget() must be used to instantiate or edit these. """ def activate(self) -> None: @@ -1319,7 +1318,7 @@ def clipboard_get_text() -> str: Category: **General Utility Functions** - Ensure that ba.clipboard_has_text returns True before calling + Ensure that ba.clipboard_has_text() returns True before calling this function. """ return str() @@ -1352,7 +1351,7 @@ def clipboard_set_text(value: str) -> None: Category: **General Utility Functions** - Ensure that ba.clipboard_available returns True before adding + Ensure that ba.clipboard_available() returns True before adding buttons/etc. that make use of this functionality. """ return None @@ -3145,7 +3144,7 @@ def timer(time: float, require the ability to do so, use the ba.Timer class instead. ##### Arguments - ###### time (float): + ###### time (float) > Length of time (in seconds by default) that the timer will wait before firing. Note that the actual delay experienced may vary depending on the timetype. (see below) diff --git a/assets/src/ba_data/python/ba/_account.py b/assets/src/ba_data/python/ba/_account.py index a072ae63..32a5f9bc 100644 --- a/assets/src/ba_data/python/ba/_account.py +++ b/assets/src/ba_data/python/ba/_account.py @@ -18,7 +18,7 @@ if TYPE_CHECKING: class AccountSubsystem: """Subsystem for account handling in the app. - Category: App Classes + Category: **App Classes** Access the single shared instance of this class at 'ba.app.plugins'. """ diff --git a/assets/src/ba_data/python/ba/_achievement.py b/assets/src/ba_data/python/ba/_achievement.py index 13634cfc..83d78081 100644 --- a/assets/src/ba_data/python/ba/_achievement.py +++ b/assets/src/ba_data/python/ba/_achievement.py @@ -65,7 +65,7 @@ ACH_LEVEL_NAMES = { class AchievementSubsystem: """Subsystem for achievement handling. - Category: App Classes + Category: **App Classes** Access the single shared instance of this class at 'ba.app.ach'. """ @@ -436,7 +436,7 @@ def _display_next_achievement() -> None: class Achievement: """Represents attributes and state for an individual achievement. - Category: App Classes + Category: **App Classes** """ def __init__(self, diff --git a/assets/src/ba_data/python/ba/_activity.py b/assets/src/ba_data/python/ba/_activity.py index 7df6e376..78a79f02 100644 --- a/assets/src/ba_data/python/ba/_activity.py +++ b/assets/src/ba_data/python/ba/_activity.py @@ -362,7 +362,7 @@ class Activity(DependencyComponent, Generic[PlayerType, TeamType]): def on_transition_out(self) -> None: """Called when your activity begins transitioning out. - Note that this may happen at any time even if ba.Activity.end has + Note that this may happen at any time even if ba.Activity.end() has not been called. """ @@ -379,11 +379,12 @@ class Activity(DependencyComponent, Generic[PlayerType, TeamType]): return UNHANDLED def has_transitioned_in(self) -> bool: - """Return whether ba.Activity.on_transition_in has been called.""" + """Return whether ba.Activity.on_transition_in() + has been called.""" return self._has_transitioned_in def has_begun(self) -> bool: - """Return whether ba.Activity.on_begin has been called.""" + """Return whether ba.Activity.on_begin() has been called.""" return self._has_begun def has_ended(self) -> bool: @@ -391,7 +392,7 @@ class Activity(DependencyComponent, Generic[PlayerType, TeamType]): return self._has_ended def is_transitioning_out(self) -> bool: - """Return whether ba.Activity.on_transition_out has been called.""" + """Return whether ba.Activity.on_transition_out() has been called.""" return self._transitioning_out def transition_in(self, prev_globals: Optional[ba.Node]) -> None: diff --git a/assets/src/ba_data/python/ba/_actor.py b/assets/src/ba_data/python/ba/_actor.py index 105bfa01..009000f0 100644 --- a/assets/src/ba_data/python/ba/_actor.py +++ b/assets/src/ba_data/python/ba/_actor.py @@ -21,7 +21,7 @@ TA = TypeVar('TA', bound='Actor') class Actor: """High level logical entities in a ba.Activity. - Category: Gameplay Classes + Category: **Gameplay Classes** Actors act as controllers, combining some number of ba.Nodes, ba.Textures, ba.Sounds, etc. into a high-level cohesive unit. @@ -33,18 +33,16 @@ class Actor: (killing off or transitioning out their nodes) when the last Python reference to them disappears, so you can use logic such as: - Example: - ```python - >>> # Create a flag Actor in our game activity: - ... from bastd.actor.flag import Flag - ... self.flag = Flag(position=(0, 10, 0)) - ... - ... # Later, destroy the flag. - ... # (provided nothing else is holding a reference to it) - ... # We could also just assign a new flag to this value. - ... # Either way, the old flag disappears. - ... self.flag = None - ``` + ##### Example + >>> # Create a flag Actor in our game activity: + ... from bastd.actor.flag import Flag + ... self.flag = Flag(position=(0, 10, 0)) + ... + ... # Later, destroy the flag. + ... # (provided nothing else is holding a reference to it) + ... # We could also just assign a new flag to this value. + ... # Either way, the old flag disappears. + ... self.flag = None This is in contrast to the behavior of the more low level ba.Nodes, which are always explicitly created and destroyed and don't care @@ -54,20 +52,18 @@ class Actor: if you want an Actor to stick around until explicitly killed regardless of references. - Another key feature of ba.Actor is its ba.Actor.handlemessage method, which + Another key feature of ba.Actor is its ba.Actor.handlemessage() method, which takes a single arbitrary object as an argument. This provides a safe way to communicate between ba.Actor, ba.Activity, ba.Session, and any other - class providing a handlemessage() method. The most universally handled + class providing a handlemessage() method. The most universally handled message type for Actors is the ba.DieMessage. Another way to kill the flag from the example above: We can safely call this on any type with a 'handlemessage' method (though its not guaranteed to always have a meaningful effect). - In this case the Actor instance will still be around, but its exists() - and is_alive() methods will both return False. - ```python + In this case the Actor instance will still be around, but its + ba.Actor.exists() and ba.Actor.is_alive() methods will both return False. >>> self.flag.handlemessage(ba.DieMessage()) - ``` """ def __init__(self) -> None: diff --git a/assets/src/ba_data/python/ba/_ads.py b/assets/src/ba_data/python/ba/_ads.py index e591bbbe..b7765b74 100644 --- a/assets/src/ba_data/python/ba/_ads.py +++ b/assets/src/ba_data/python/ba/_ads.py @@ -15,7 +15,7 @@ if TYPE_CHECKING: class AdsSubsystem: """Subsystem for ads functionality in the app. - Category: App Classes + Category: **App Classes** Access the single shared instance of this class at 'ba.app.ads'. """ diff --git a/assets/src/ba_data/python/ba/_app.py b/assets/src/ba_data/python/ba/_app.py index d9bd3383..c7bd0e65 100644 --- a/assets/src/ba_data/python/ba/_app.py +++ b/assets/src/ba_data/python/ba/_app.py @@ -27,7 +27,7 @@ if TYPE_CHECKING: class App: """A class for high level app functionality and state. - Category: App Classes + Category: **App Classes** Use ba.app to access the single shared instance of this class. diff --git a/assets/src/ba_data/python/ba/_appconfig.py b/assets/src/ba_data/python/ba/_appconfig.py index 611483e8..5e1e1726 100644 --- a/assets/src/ba_data/python/ba/_appconfig.py +++ b/assets/src/ba_data/python/ba/_appconfig.py @@ -14,7 +14,7 @@ if TYPE_CHECKING: class AppConfig(dict): """A special dict that holds the game's persistent configuration values. - Category: App Classes + Category: **App Classes** It also provides methods for fetching values with app-defined fallback defaults, applying contained values to the game, and committing the @@ -155,7 +155,7 @@ def read_config() -> tuple[AppConfig, bool]: def commit_app_config(force: bool = False) -> None: """Commit the config to persistent storage. - Category: General Utility Functions + Category: **General Utility Functions** (internal) """ diff --git a/assets/src/ba_data/python/ba/_campaign.py b/assets/src/ba_data/python/ba/_campaign.py index 76942876..915fc4cd 100644 --- a/assets/src/ba_data/python/ba/_campaign.py +++ b/assets/src/ba_data/python/ba/_campaign.py @@ -25,7 +25,7 @@ def getcampaign(name: str) -> ba.Campaign: class Campaign: """Represents a unique set or series of ba.Level-s. - Category: App Classes + Category: **App Classes** """ def __init__(self, name: str, sequential: bool = True): diff --git a/assets/src/ba_data/python/ba/_collision.py b/assets/src/ba_data/python/ba/_collision.py index e9db1e8e..d44c0f4d 100644 --- a/assets/src/ba_data/python/ba/_collision.py +++ b/assets/src/ba_data/python/ba/_collision.py @@ -16,7 +16,7 @@ if TYPE_CHECKING: class Collision: """A class providing info about occurring collisions. - Category: Gameplay Classes + Category: **Gameplay Classes** """ @property @@ -67,6 +67,6 @@ _collision = Collision() def getcollision() -> Collision: """Return the in-progress collision. - Category: Gameplay Functions + Category: **Gameplay Functions** """ return _collision diff --git a/assets/src/ba_data/python/ba/_coopgame.py b/assets/src/ba_data/python/ba/_coopgame.py index 1d771b5e..79ba755f 100644 --- a/assets/src/ba_data/python/ba/_coopgame.py +++ b/assets/src/ba_data/python/ba/_coopgame.py @@ -21,7 +21,7 @@ TeamType = TypeVar('TeamType', bound='ba.Team') class CoopGameActivity(GameActivity[PlayerType, TeamType]): """Base class for cooperative-mode games. - Category: Gameplay Classes + Category: **Gameplay Classes** """ # We can assume our session is a CoopSession. diff --git a/assets/src/ba_data/python/ba/_coopsession.py b/assets/src/ba_data/python/ba/_coopsession.py index 15259ea2..c2c08020 100644 --- a/assets/src/ba_data/python/ba/_coopsession.py +++ b/assets/src/ba_data/python/ba/_coopsession.py @@ -19,25 +19,23 @@ TEAM_NAMES = ['Good Guys'] class CoopSession(Session): """A ba.Session which runs cooperative-mode games. - Category: Gameplay Classes + Category: **Gameplay Classes** These generally consist of 1-4 players against the computer and include functionality such as high score lists. - - Attributes: - - campaign - The ba.Campaign instance this Session represents, or None if - there is no associated Campaign. """ + use_teams = True use_team_colors = False allow_mid_activity_joins = False # Note: even though these are instance vars, we annotate them at the # class level so that docs generation can access their types. + campaign: Optional[ba.Campaign] + """The ba.Campaign instance this Session represents, or None if + there is no associated Campaign.""" def __init__(self) -> None: """Instantiate a co-op mode session.""" diff --git a/assets/src/ba_data/python/ba/_dependency.py b/assets/src/ba_data/python/ba/_dependency.py index 87a3116e..f46cae6a 100644 --- a/assets/src/ba_data/python/ba/_dependency.py +++ b/assets/src/ba_data/python/ba/_dependency.py @@ -19,7 +19,7 @@ T = TypeVar('T', bound='DependencyComponent') class Dependency(Generic[T]): """A dependency on a DependencyComponent (with an optional config). - Category: Dependency Classes + Category: **Dependency Classes** This class is used to request and access functionality provided by other DependencyComponent classes from a DependencyComponent class. @@ -87,7 +87,7 @@ class Dependency(Generic[T]): class DependencyComponent: """Base class for all classes that can act as or use dependencies. - category: Dependency Classes + Category: **Dependency Classes** """ _dep_entry: weakref.ref[DependencyEntry] @@ -165,7 +165,7 @@ class DependencyEntry: class DependencySet(Generic[T]): """Set of resolved dependencies and their associated data. - Category: Dependency Classes + Category: **Dependency Classes** To use DependencyComponents, a set must be created, resolved, and then loaded. The DependencyComponents are only valid while the set remains @@ -291,7 +291,7 @@ class DependencySet(Generic[T]): class AssetPackage(DependencyComponent): """ba.DependencyComponent representing a bundled package of game assets. - Category: Asset Classes + Category: **Asset Classes** """ def __init__(self) -> None: diff --git a/assets/src/ba_data/python/ba/_dualteamsession.py b/assets/src/ba_data/python/ba/_dualteamsession.py index 427e7063..0b7a327b 100644 --- a/assets/src/ba_data/python/ba/_dualteamsession.py +++ b/assets/src/ba_data/python/ba/_dualteamsession.py @@ -15,7 +15,7 @@ if TYPE_CHECKING: class DualTeamSession(MultiTeamSession): """ba.Session type for teams mode games. - Category: Gameplay Classes + Category: **Gameplay Classes** """ # Base class overrides: diff --git a/assets/src/ba_data/python/ba/_error.py b/assets/src/ba_data/python/ba/_error.py index c9e75fcb..bb82a78a 100644 --- a/assets/src/ba_data/python/ba/_error.py +++ b/assets/src/ba_data/python/ba/_error.py @@ -16,7 +16,7 @@ if TYPE_CHECKING: class DependencyError(Exception): """Exception raised when one or more ba.Dependency items are missing. - category: Exception Classes + Category: **Exception Classes** (this will generally be missing assets). """ @@ -34,7 +34,7 @@ class DependencyError(Exception): class ContextError(Exception): """Exception raised when a call is made in an invalid context. - category: Exception Classes + Category: **Exception Classes** Examples of this include calling UI functions within an Activity context or calling scene manipulation functions outside of a game context. @@ -44,91 +44,91 @@ class ContextError(Exception): class NotFoundError(Exception): """Exception raised when a referenced object does not exist. - category: Exception Classes + Category: **Exception Classes** """ class PlayerNotFoundError(NotFoundError): """Exception raised when an expected ba.Player does not exist. - category: Exception Classes + Category: **Exception Classes** """ class SessionPlayerNotFoundError(NotFoundError): """Exception raised when an expected ba.SessionPlayer does not exist. - category: Exception Classes + Category: **Exception Classes** """ class TeamNotFoundError(NotFoundError): """Exception raised when an expected ba.Team does not exist. - category: Exception Classes + Category: **Exception Classes** """ class DelegateNotFoundError(NotFoundError): """Exception raised when an expected delegate object does not exist. - category: Exception Classes + Category: **Exception Classes** """ class SessionTeamNotFoundError(NotFoundError): """Exception raised when an expected ba.SessionTeam does not exist. - category: Exception Classes + Category: **Exception Classes** """ class NodeNotFoundError(NotFoundError): """Exception raised when an expected ba.Node does not exist. - category: Exception Classes + Category: **Exception Classes** """ class ActorNotFoundError(NotFoundError): """Exception raised when an expected ba.Actor does not exist. - category: Exception Classes + Category: **Exception Classes** """ class ActivityNotFoundError(NotFoundError): """Exception raised when an expected ba.Activity does not exist. - category: Exception Classes + Category: **Exception Classes** """ class SessionNotFoundError(NotFoundError): """Exception raised when an expected ba.Session does not exist. - category: Exception Classes + Category: **Exception Classes** """ class InputDeviceNotFoundError(NotFoundError): """Exception raised when an expected ba.InputDevice does not exist. - category: Exception Classes + Category: **Exception Classes** """ class WidgetNotFoundError(NotFoundError): """Exception raised when an expected ba.Widget does not exist. - category: Exception Classes + Category: **Exception Classes** """ def print_exception(*args: Any, **keywds: Any) -> None: """Print info about an exception along with pertinent context state. - category: General Utility Functions + Category: **General Utility Functions** Prints all arguments provided along with various info about the current context and the outstanding exception. @@ -168,7 +168,7 @@ def print_exception(*args: Any, **keywds: Any) -> None: def print_error(err_str: str, once: bool = False) -> None: """Print info about an error along with pertinent context state. - category: General Utility Functions + Category: **General Utility Functions** Prints all positional arguments provided along with various info about the current context. diff --git a/assets/src/ba_data/python/ba/_freeforallsession.py b/assets/src/ba_data/python/ba/_freeforallsession.py index c0ceee99..a33c8278 100644 --- a/assets/src/ba_data/python/ba/_freeforallsession.py +++ b/assets/src/ba_data/python/ba/_freeforallsession.py @@ -16,7 +16,7 @@ if TYPE_CHECKING: class FreeForAllSession(MultiTeamSession): """ba.Session type for free-for-all mode games. - Category: Gameplay Classes + Category: **Gameplay Classes** """ use_teams = False use_team_colors = False diff --git a/assets/src/ba_data/python/ba/_gameactivity.py b/assets/src/ba_data/python/ba/_gameactivity.py index c7d633e0..129fae2f 100644 --- a/assets/src/ba_data/python/ba/_gameactivity.py +++ b/assets/src/ba_data/python/ba/_gameactivity.py @@ -31,7 +31,7 @@ TeamType = TypeVar('TeamType', bound='ba.Team') class GameActivity(Activity[PlayerType, TeamType]): """Common base class for all game ba.Activities. - category: Gameplay Classes + Category: **Gameplay Classes** """ # pylint: disable=too-many-public-methods diff --git a/assets/src/ba_data/python/ba/_gameresults.py b/assets/src/ba_data/python/ba/_gameresults.py index f4b3ebd1..159a6d58 100644 --- a/assets/src/ba_data/python/ba/_gameresults.py +++ b/assets/src/ba_data/python/ba/_gameresults.py @@ -27,10 +27,10 @@ class GameResults: """ Results for a completed game. - Category: Gameplay Classes + Category: **Gameplay Classes** Upon completion, a game should fill one of these out and pass it to its - ba.Activity.end() call. + ba.Activity.end call. """ def __init__(self) -> None: diff --git a/assets/src/ba_data/python/ba/_gameutils.py b/assets/src/ba_data/python/ba/_gameutils.py index d337f3df..110535a8 100644 --- a/assets/src/ba_data/python/ba/_gameutils.py +++ b/assets/src/ba_data/python/ba/_gameutils.py @@ -29,7 +29,7 @@ TROPHY_CHARS = { class GameTip: """Defines a tip presentable to the user at the start of a game. - Category: Gameplay Classes + Category: **Gameplay Classes** """ text: str icon: Optional[ba.Texture] = None @@ -53,7 +53,7 @@ def animate(node: ba.Node, suppress_format_warning: bool = False) -> ba.Node: """Animate values on a target ba.Node. - Category: Gameplay Functions + Category: **Gameplay Functions** Creates an 'animcurve' node with the provided values and time as an input, connect it to the provided attribute, and set it to die with the target. @@ -127,9 +127,9 @@ def animate_array(node: ba.Node, suppress_format_warning: bool = False) -> None: """Animate an array of values on a target ba.Node. - Category: Gameplay Functions + Category: **Gameplay Functions** - Like ba.animate(), but operates on array attributes. + Like ba.animate, but operates on array attributes. """ # pylint: disable=too-many-locals combine = _ba.newnode('combine', owner=node, attrs={'size': size}) @@ -198,7 +198,7 @@ def show_damage_count(damage: str, position: Sequence[float], direction: Sequence[float]) -> None: """Pop up a damage count at a position in space. - Category: Gameplay Functions + Category: **Gameplay Functions** """ lifespan = 1.0 app = _ba.app @@ -253,7 +253,7 @@ def timestring(timeval: float, suppress_format_warning: bool = False) -> ba.Lstr: """Generate a ba.Lstr for displaying a time value. - Category: General Utility Functions + Category: **General Utility Functions** Given a time value, returns a ba.Lstr with: (hours if > 0 ) : minutes : seconds : (centiseconds if centi=True). @@ -321,7 +321,7 @@ def timestring(timeval: float, def cameraflash(duration: float = 999.0) -> None: """Create a strobing camera flash effect. - Category: Gameplay Functions + Category: **Gameplay Functions** (as seen when a team wins a game) Duration is in seconds. diff --git a/assets/src/ba_data/python/ba/_general.py b/assets/src/ba_data/python/ba/_general.py index bee3fac5..b28731c1 100644 --- a/assets/src/ba_data/python/ba/_general.py +++ b/assets/src/ba_data/python/ba/_general.py @@ -24,7 +24,7 @@ if TYPE_CHECKING: class Existable(Protocol): """A Protocol for objects supporting an exists() method. - Category: Protocols + Category: **Protocols** """ def exists(self) -> bool: @@ -39,7 +39,7 @@ T = TypeVar('T') def existing(obj: Optional[ExistableType]) -> Optional[ExistableType]: """Convert invalid references to None for any ba.Existable object. - Category: Gameplay Functions + Category: **Gameplay Functions** To best support type checking, it is important that invalid references not be passed around and instead get converted to values of None. @@ -59,7 +59,7 @@ def existing(obj: Optional[ExistableType]) -> Optional[ExistableType]: def getclass(name: str, subclassof: type[T]) -> type[T]: """Given a full class name such as foo.bar.MyClass, return the class. - Category: General Utility Functions + Category: **General Utility Functions** The class will be checked to make sure it is a subclass of the provided 'subclassof' class, and a TypeError will be raised if not. @@ -140,7 +140,7 @@ def get_type_name(cls: type) -> str: class _WeakCall: """Wrap a callable and arguments into a single callable object. - Category: General Utility Classes + Category: **General Utility Classes** When passed a bound method as the callable, the instance portion of it is weak-referenced, meaning the underlying instance is @@ -150,40 +150,34 @@ class _WeakCall: Think of this as a handy way to tell an object to do something at some point in the future if it happens to still exist. - Examples: - EXAMPLE A: this code will create a FooClass instance and call its - bar() method 5 seconds later; it will be kept alive even though - we overwrite its variable with None because the bound method - we pass as a timer callback (foo.bar) strong-references it - ```python - >>> foo = FooClass() - ... ba.timer(5.0, foo.bar) - ... foo = None - ``` + ##### Examples + **EXAMPLE A:** this code will create a FooClass instance and call its + bar() method 5 seconds later; it will be kept alive even though + we overwrite its variable with None because the bound method + we pass as a timer callback (foo.bar) strong-references it + >>> foo = FooClass() + ... ba.timer(5.0, foo.bar) + ... foo = None - EXAMPLE B: this code will *not* keep our object alive; it will die - when we overwrite it with None and the timer will be a no-op when it - fires - ```python - >>> foo = FooClass() - ... ba.timer(5.0, ba.WeakCall(foo.bar)) - ... foo = None - ``` + **EXAMPLE B:** This code will *not* keep our object alive; it will die + when we overwrite it with None and the timer will be a no-op when it + fires + >>> foo = FooClass() + ... ba.timer(5.0, ba.WeakCall(foo.bar)) + ... foo = None - EXAMPLE C: Wrap a method call with some positional and keyword args: - ```python - >>> myweakcall = ba.WeakCall(self.dostuff, argval1, - ... namedarg=argval2) - ... # Now we have a single callable to run that whole mess. - ... # The same as calling myobj.dostuff(argval1, namedarg=argval2) - ... # (provided my_obj still exists; this will do nothing - ... # otherwise). - ... myweakcall() - ``` + **EXAMPLE C:** Wrap a method call with some positional and keyword args: + >>> myweakcall = ba.WeakCall(self.dostuff, argval1, + ... namedarg=argval2) + ... # Now we have a single callable to run that whole mess. + ... # The same as calling myobj.dostuff(argval1, namedarg=argval2) + ... # (provided my_obj still exists; this will do nothing + ... # otherwise). + ... myweakcall() - Note: additional args and keywords you provide to the WeakCall() - constructor are stored as regular strong-references; you'll need - to wrap them in weakrefs manually if desired. + Note: additional args and keywords you provide to the WeakCall() + constructor are stored as regular strong-references; you'll need + to wrap them in weakrefs manually if desired. """ def __init__(self, *args: Any, **keywds: Any) -> None: @@ -219,7 +213,7 @@ class _WeakCall: class _Call: """Wraps a callable and arguments into a single callable object. - Category: General Utility Classes + Category: **General Utility Classes** The callable is strong-referenced so it won't die until this object does. @@ -236,14 +230,12 @@ class _Call: Pass a callable as the first arg, followed by any number of arguments or keywords. - Example: - Wrap a method call with 1 positional and 1 keyword arg: - ```python - >>> mycall = ba.Call(myobj.dostuff, argval, namedarg=argval2) - ... # Now we have a single callable to run that whole mess. - ... # ..the same as calling myobj.dostuff(argval, namedarg=argval2) - ... mycall() - ``` + ##### Example + Wrap a method call with 1 positional and 1 keyword arg: + >>> mycall = ba.Call(myobj.dostuff, argval, namedarg=argval2) + ... # Now we have a single callable to run that whole mess. + ... # ..the same as calling myobj.dostuff(argval, namedarg=argval2) + ... mycall() """ self._call = args[0] self._args = args[1:] @@ -292,7 +284,7 @@ class WeakMethod: def verify_object_death(obj: object) -> None: """Warn if an object does not get freed within a short period. - Category: General Utility Functions + Category: **General Utility Functions** This can be handy to detect and prevent memory/resource leaks. """ @@ -313,7 +305,7 @@ def verify_object_death(obj: object) -> None: def print_active_refs(obj: Any) -> None: """Print info about things referencing a given object. - Category: General Utility Functions + Category: **General Utility Functions** Useful for tracking down cyclical references and causes for zombie objects. """ @@ -370,7 +362,7 @@ def _verify_object_death(wref: weakref.ref) -> None: def storagename(suffix: str = None) -> str: """Generate a unique name for storing class data in shared places. - Category: General Utility Functions + Category: **General Utility Functions** This consists of a leading underscore, the module path at the call site with dots replaced by underscores, the containing class's @@ -380,19 +372,17 @@ def storagename(suffix: str = None) -> str: Note that this will function even if called in the class definition. - Examples: - Generate a unique name for storage purposes: - ```python - >>> class MyThingie: - ... # This will give something like - ... # '_mymodule_submodule_mythingie_data'. - ... _STORENAME = ba.storagename('data') - ... - ... # Use that name to store some data in the Activity we were - ... # passed. - ... def __init__(self, activity): - ... activity.customdata[self._STORENAME] = {} - ``` + ##### Examples + Generate a unique name for storage purposes: + >>> class MyThingie: + ... # This will give something like + ... # '_mymodule_submodule_mythingie_data'. + ... _STORENAME = ba.storagename('data') + ... + ... # Use that name to store some data in the Activity we were + ... # passed. + ... def __init__(self, activity): + ... activity.customdata[self._STORENAME] = {} """ frame = inspect.currentframe() if frame is None: diff --git a/assets/src/ba_data/python/ba/_keyboard.py b/assets/src/ba_data/python/ba/_keyboard.py index 8502caaa..36dfc183 100644 --- a/assets/src/ba_data/python/ba/_keyboard.py +++ b/assets/src/ba_data/python/ba/_keyboard.py @@ -13,7 +13,7 @@ if TYPE_CHECKING: class Keyboard: """Chars definitions for on-screen keyboard. - Category: App Classes + Category: **App Classes** Keyboards are discoverable by the meta-tag system and the user can select which one they want to use. diff --git a/assets/src/ba_data/python/ba/_language.py b/assets/src/ba_data/python/ba/_language.py index 5d9894b7..6d431ced 100644 --- a/assets/src/ba_data/python/ba/_language.py +++ b/assets/src/ba_data/python/ba/_language.py @@ -17,7 +17,7 @@ if TYPE_CHECKING: class LanguageSubsystem: """Wraps up language related app functionality. - Category: App Classes + Category: **App Classes** To use this class, access the single instance of it at 'ba.app.lang'. """ @@ -367,7 +367,7 @@ class LanguageSubsystem: class Lstr: """Used to define strings in a language-independent way. - category: General Utility Classes + Category: **General Utility Classes** These should be used whenever possible in place of hard-coded strings so that in-game or UI elements show up correctly on all clients in their @@ -376,36 +376,28 @@ class Lstr: To see available resource keys, look at any of the bs_language_*.py files in the game or the translations pages at bombsquadgame.com/translate. - Examples: - EXAMPLE 1: specify a string from a resource path - ```python - >>> mynode.text = ba.Lstr(resource='audioSettingsWindow.titleText') - ``` + ##### Examples + EXAMPLE 1: specify a string from a resource path + >>> mynode.text = ba.Lstr(resource='audioSettingsWindow.titleText') - EXAMPLE 2: specify a translated string via a category and english - value; if a translated value is available, it will be used; otherwise - the english value will be. To see available translation categories, - look under the 'translations' resource section. - ```python - >>> mynode.text = ba.Lstr(translate=('gameDescriptions', - ... 'Defeat all enemies')) - ``` + EXAMPLE 2: specify a translated string via a category and english + value; if a translated value is available, it will be used; otherwise + the english value will be. To see available translation categories, + look under the 'translations' resource section. + >>> mynode.text = ba.Lstr(translate=('gameDescriptions', + ... 'Defeat all enemies')) - EXAMPLE 3: specify a raw value and some substitutions. Substitutions - can be used with resource and translate modes as well. - ```python - >>> mynode.text = ba.Lstr(value='${A} / ${B}', - ... subs=[('${A}', str(score)), ('${B}', str(total))]) - ``` + EXAMPLE 3: specify a raw value and some substitutions. Substitutions + can be used with resource and translate modes as well. + >>> mynode.text = ba.Lstr(value='${A} / ${B}', + ... subs=[('${A}', str(score)), ('${B}', str(total))]) - EXAMPLE 4: ba.Lstr's can be nested. This example would display the - resource at res_a but replace ${NAME} with the value of the - resource at res_b - ```python - >>> mytextnode.text = ba.Lstr( - ... resource='res_a', - ... subs=[('${NAME}', ba.Lstr(resource='res_b'))]) - ``` + EXAMPLE 4: ba.Lstr's can be nested. This example would display the + resource at res_a but replace ${NAME} with the value of the + resource at res_b + >>> mytextnode.text = ba.Lstr( + ... resource='res_a', + ... subs=[('${NAME}', ba.Lstr(resource='res_b'))]) """ # pylint: disable=dangerous-default-value diff --git a/assets/src/ba_data/python/ba/_level.py b/assets/src/ba_data/python/ba/_level.py index 53e67f1d..968610a9 100644 --- a/assets/src/ba_data/python/ba/_level.py +++ b/assets/src/ba_data/python/ba/_level.py @@ -17,7 +17,7 @@ if TYPE_CHECKING: class Level: """An entry in a ba.Campaign consisting of a name, game type, and settings. - category: Gameplay Classes + Category: **Gameplay Classes** """ def __init__(self, diff --git a/assets/src/ba_data/python/ba/_map.py b/assets/src/ba_data/python/ba/_map.py index f8739a7c..be653942 100644 --- a/assets/src/ba_data/python/ba/_map.py +++ b/assets/src/ba_data/python/ba/_map.py @@ -18,7 +18,7 @@ if TYPE_CHECKING: def preload_map_preview_media() -> None: """Preload media needed for map preview UIs. - Category: Asset Functions + Category: **Asset Functions** """ _ba.getmodel('level_select_button_opaque') _ba.getmodel('level_select_button_transparent') @@ -31,7 +31,7 @@ def preload_map_preview_media() -> None: def get_filtered_map_name(name: str) -> str: """Filter a map name to account for name changes, etc. - Category: Asset Functions + Category: **Asset Functions** This can be used to support old playlists, etc. """ @@ -46,7 +46,7 @@ def get_filtered_map_name(name: str) -> str: def get_map_display_string(name: str) -> ba.Lstr: """Return a ba.Lstr for displaying a given map\'s name. - Category: Asset Functions + Category: **Asset Functions** """ from ba import _language return _language.Lstr(translate=('mapsNames', name)) @@ -55,7 +55,7 @@ def get_map_display_string(name: str) -> ba.Lstr: def getmaps(playtype: str) -> list[str]: """Return a list of ba.Map types supporting a playtype str. - Category: Asset Functions + Category: **Asset Functions** Maps supporting a given playtype must provide a particular set of features and lend themselves to a certain style of play. @@ -104,7 +104,7 @@ def getmaps(playtype: str) -> list[str]: def get_unowned_maps() -> list[str]: """Return the list of local maps not owned by the current account. - Category: Asset Functions + Category: **Asset Functions** """ from ba import _store unowned_maps: set[str] = set() @@ -120,7 +120,7 @@ def get_unowned_maps() -> list[str]: def get_map_class(name: str) -> type[ba.Map]: """Return a map type given a name. - Category: Asset Functions + Category: **Asset Functions** """ name = get_filtered_map_name(name) try: @@ -133,7 +133,7 @@ def get_map_class(name: str) -> type[ba.Map]: class Map(Actor): """A game map. - Category: Gameplay Classes + Category: **Gameplay Classes** Consists of a collection of terrain nodes, metadata, and other functionality comprising a game map. diff --git a/assets/src/ba_data/python/ba/_messages.py b/assets/src/ba_data/python/ba/_messages.py index 92a7c366..aa22cad4 100644 --- a/assets/src/ba_data/python/ba/_messages.py +++ b/assets/src/ba_data/python/ba/_messages.py @@ -50,24 +50,19 @@ class DeathType(Enum): class DieMessage: """A message telling an object to die. - Category: Message Classes + Category: **Message Classes** Most ba.Actor-s respond to this. - - Attributes: - - immediate - If this is set to True, the actor should disappear immediately. - This is for 'removing' stuff from the game more so than 'killing' - it. If False, the actor should die a 'normal' death and can take - its time with lingering corpses, sound effects, etc. - - how - The particular reason for death. - """ + immediate: bool = False + """If this is set to True, the actor should disappear immediately. + This is for 'removing' stuff from the game more so than 'killing' + it. If False, the actor should die a 'normal' death and can take + its time with lingering corpses, sound effects, etc.""" + how: DeathType = DeathType.GENERIC + """The particular reason for death.""" PlayerType = TypeVar('PlayerType', bound='ba.Player') @@ -76,19 +71,15 @@ PlayerType = TypeVar('PlayerType', bound='ba.Player') class PlayerDiedMessage: """A message saying a ba.Player has died. - category: Message Classes - - Attributes: - - killed - If True, the player was killed; - If False, they left the game or the round ended. - - how - The particular type of death. + Category: **Message Classes** """ + killed: bool + """If True, the player was killed; + If False, they left the game or the round ended.""" + how: ba.DeathType + """The particular type of death.""" def __init__(self, player: ba.Player, was_killed: bool, killerplayer: Optional[ba.Player], how: ba.DeathType): @@ -132,41 +123,34 @@ class PlayerDiedMessage: class StandMessage: """A message telling an object to move to a position in space. - Category: Message Classes + Category: **Message Classes** Used when teleporting players to home base, etc. - - Attributes: - - position - Where to move to. - - angle - The angle to face (in degrees) """ + position: Sequence[float] = (0.0, 0.0, 0.0) + """Where to move to.""" + angle: float = 0.0 + """The angle to face (in degrees)""" @dataclass class PickUpMessage: """Tells an object that it has picked something up. - Category: Message Classes - - Attributes: - - node - The ba.Node that is getting picked up. + Category: **Message Classes** """ + node: ba.Node + """The ba.Node that is getting picked up.""" @dataclass class DropMessage: """Tells an object that it has dropped what it was holding. - Category: Message Classes + Category: **Message Classes** """ @@ -174,35 +158,29 @@ class DropMessage: class PickedUpMessage: """Tells an object that it has been picked up by something. - Category: Message Classes - - Attributes: - - node - The ba.Node doing the picking up. + Category: **Message Classes** """ + node: ba.Node + """The ba.Node doing the picking up.""" @dataclass class DroppedMessage: """Tells an object that it has been dropped. - Category: Message Classes - - Attributes: - - node - The ba.Node doing the dropping. + Category: **Message Classes** """ + node: ba.Node + """The ba.Node doing the dropping.""" @dataclass class ShouldShatterMessage: """Tells an object that it should shatter. - Category: Message Classes + Category: **Message Classes** """ @@ -210,21 +188,18 @@ class ShouldShatterMessage: class ImpactDamageMessage: """Tells an object that it has been jarred violently. - Category: Message Classes - - Attributes: - - intensity - The intensity of the impact. + Category: **Message Classes** """ + intensity: float + """The intensity of the impact.""" @dataclass class FreezeMessage: """Tells an object to become frozen. - Category: Message Classes + Category: **Message Classes** As seen in the effects of an ice ba.Bomb. """ @@ -234,7 +209,7 @@ class FreezeMessage: class ThawMessage: """Tells an object to stop being frozen. - Category: Message Classes + Category: **Message Classes** """ @@ -242,20 +217,17 @@ class ThawMessage: class CelebrateMessage: """Tells an object to celebrate. - Category: Message Classes - - Attributes: - - duration - Amount of time to celebrate in seconds. + Category: **Message Classes** """ + duration: float = 10.0 + """Amount of time to celebrate in seconds.""" class HitMessage: """Tells an object it has been hit in some way. - Category: Message Classes + Category: **Message Classes** This is used by punches, explosions, etc to convey their effect to a target. diff --git a/assets/src/ba_data/python/ba/_meta.py b/assets/src/ba_data/python/ba/_meta.py index 7776a5b3..017ff85b 100644 --- a/assets/src/ba_data/python/ba/_meta.py +++ b/assets/src/ba_data/python/ba/_meta.py @@ -37,7 +37,7 @@ class ScanResults: class MetadataSubsystem: """Subsystem for working with script metadata in the app. - Category: App Classes + Category: **App Classes** Access the single shared instance of this class at 'ba.app.meta'. """ diff --git a/assets/src/ba_data/python/ba/_multiteamsession.py b/assets/src/ba_data/python/ba/_multiteamsession.py index 8a1b7bae..29b4c1e7 100644 --- a/assets/src/ba_data/python/ba/_multiteamsession.py +++ b/assets/src/ba_data/python/ba/_multiteamsession.py @@ -22,7 +22,7 @@ DEFAULT_TEAM_NAMES = ('Blue', 'Red') class MultiTeamSession(Session): """Common base class for ba.DualTeamSession and ba.FreeForAllSession. - Category: Gameplay Classes + Category: **Gameplay Classes** Free-for-all-mode is essentially just teams-mode with each ba.Player having their own ba.Team, so there is much overlap in functionality. diff --git a/assets/src/ba_data/python/ba/_music.py b/assets/src/ba_data/python/ba/_music.py index 7cf3815f..bb417661 100644 --- a/assets/src/ba_data/python/ba/_music.py +++ b/assets/src/ba_data/python/ba/_music.py @@ -18,7 +18,7 @@ if TYPE_CHECKING: class MusicType(Enum): """Types of music available to play in-game. - Category: Enums + Category: **Enums** These do not correspond to specific pieces of music, but rather to 'situations'. The actual music played for each type can be overridden @@ -51,7 +51,7 @@ class MusicType(Enum): class MusicPlayMode(Enum): """Influences behavior when playing music. - Category: Enums + Category: **Enums** """ REGULAR = 'regular' TEST = 'test' @@ -61,7 +61,7 @@ class MusicPlayMode(Enum): class AssetSoundtrackEntry: """A music entry using an internal asset. - Category: App Classes + Category: **App Classes** """ assetname: str volume: float = 1.0 @@ -120,7 +120,7 @@ ASSET_SOUNDTRACK_ENTRIES: dict[MusicType, AssetSoundtrackEntry] = { class MusicSubsystem: """Subsystem for music playback in the app. - Category: App Classes + Category: **App Classes** Access the single shared instance of this class at 'ba.app.music'. """ @@ -385,7 +385,7 @@ class MusicSubsystem: class MusicPlayer: """Wrangles soundtrack music playback. - Category: App Classes + Category: **App Classes** Music can be played either through the game itself or via a platform-specific external player. @@ -474,7 +474,7 @@ def setmusic(musictype: Optional[ba.MusicType], continuous: bool = False) -> None: """Set the app to play (or stop playing) a certain type of music. - category: Gameplay Functions + category: **Gameplay Functions** This function will handle loading and playing sound assets as necessary, and also supports custom user soundtracks on specific platforms so the diff --git a/assets/src/ba_data/python/ba/_nodeactor.py b/assets/src/ba_data/python/ba/_nodeactor.py index 756a7fce..e9e78a23 100644 --- a/assets/src/ba_data/python/ba/_nodeactor.py +++ b/assets/src/ba_data/python/ba/_nodeactor.py @@ -17,7 +17,7 @@ if TYPE_CHECKING: class NodeActor(Actor): """A simple ba.Actor type that wraps a single ba.Node. - Category: Gameplay Classes + Category: **Gameplay Classes** This Actor will delete its Node when told to die, and it's exists() call will return whether the Node still exists or not. diff --git a/assets/src/ba_data/python/ba/_plugin.py b/assets/src/ba_data/python/ba/_plugin.py index 7637717c..a56e4a73 100644 --- a/assets/src/ba_data/python/ba/_plugin.py +++ b/assets/src/ba_data/python/ba/_plugin.py @@ -16,7 +16,7 @@ if TYPE_CHECKING: class PluginSubsystem: """Subsystem for plugin handling in the app. - Category: App Classes + Category: **App Classes** Access the single shared instance of this class at 'ba.app.plugins'. """ @@ -96,7 +96,7 @@ class PluginSubsystem: class PotentialPlugin: """Represents a ba.Plugin which can potentially be loaded. - Category: App Classes + Category: **App Classes** These generally represent plugins which were detected by the meta-tag scan. However they may also represent plugins which @@ -111,7 +111,7 @@ class PotentialPlugin: class Plugin: """A plugin to alter app behavior in some way. - Category: App Classes + Category: **App Classes** Plugins are discoverable by the meta-tag system and the user can select which ones they want to activate. diff --git a/assets/src/ba_data/python/ba/_powerup.py b/assets/src/ba_data/python/ba/_powerup.py index 520d3020..246cf7bb 100644 --- a/assets/src/ba_data/python/ba/_powerup.py +++ b/assets/src/ba_data/python/ba/_powerup.py @@ -16,31 +16,27 @@ if TYPE_CHECKING: class PowerupMessage: """A message telling an object to accept a powerup. - Category: Message Classes + Category: **Message Classes** This message is normally received by touching a ba.PowerupBox. - - Attributes: - - poweruptype - The type of powerup to be granted (a string). - See ba.Powerup.poweruptype for available type values. - - sourcenode - The node the powerup game from, or None otherwise. - If a powerup is accepted, a ba.PowerupAcceptMessage should be sent - back to the sourcenode to inform it of the fact. This will generally - cause the powerup box to make a sound and disappear or whatnot. """ + poweruptype: str + """The type of powerup to be granted (a string). + See ba.Powerup.poweruptype for available type values.""" + sourcenode: Optional[ba.Node] = None + """The node the powerup game from, or None otherwise. + If a powerup is accepted, a ba.PowerupAcceptMessage should be sent + back to the sourcenode to inform it of the fact. This will generally + cause the powerup box to make a sound and disappear or whatnot.""" @dataclass class PowerupAcceptMessage: """A message informing a ba.Powerup that it was accepted. - Category: Message Classes + Category: **Message Classes** This is generally sent in response to a ba.PowerupMessage to inform the box (or whoever granted it) that it can go away. diff --git a/assets/src/ba_data/python/ba/_score.py b/assets/src/ba_data/python/ba/_score.py index b5272118..8b8d009a 100644 --- a/assets/src/ba_data/python/ba/_score.py +++ b/assets/src/ba_data/python/ba/_score.py @@ -16,7 +16,7 @@ if TYPE_CHECKING: class ScoreType(Enum): """Type of scores. - Category: Enums + Category: **Enums** """ SECONDS = 's' MILLISECONDS = 'ms' @@ -27,7 +27,7 @@ class ScoreType(Enum): class ScoreConfig: """Settings for how a game handles scores. - Category: Gameplay Classes + Category: **Gameplay Classes** """ label: str = 'Score' diff --git a/assets/src/ba_data/python/ba/_servermode.py b/assets/src/ba_data/python/ba/_servermode.py index 6df38d79..87e525d7 100644 --- a/assets/src/ba_data/python/ba/_servermode.py +++ b/assets/src/ba_data/python/ba/_servermode.py @@ -77,7 +77,7 @@ def _cmd(command_data: bytes) -> None: class ServerController: """Overall controller for the app in server mode. - Category: App Classes + Category: **App Classes** """ def __init__(self, config: ServerConfig) -> None: diff --git a/assets/src/ba_data/python/ba/_session.py b/assets/src/ba_data/python/ba/_session.py index 32041f9b..d0ee1264 100644 --- a/assets/src/ba_data/python/ba/_session.py +++ b/assets/src/ba_data/python/ba/_session.py @@ -19,7 +19,7 @@ if TYPE_CHECKING: class Session: """Defines a high level series of ba.Activity-es with a common purpose. - Category: Gameplay Classes + Category: **Gameplay Classes** Examples of sessions are ba.FreeForAllSession, ba.DualTeamSession, and ba.CoopSession. diff --git a/assets/src/ba_data/python/ba/_stats.py b/assets/src/ba_data/python/ba/_stats.py index 675bfeb5..282545b4 100644 --- a/assets/src/ba_data/python/ba/_stats.py +++ b/assets/src/ba_data/python/ba/_stats.py @@ -21,7 +21,7 @@ if TYPE_CHECKING: class PlayerScoredMessage: """Informs something that a ba.Player scored. - Category: Message Classes + Category: **Message Classes** """ score: int @@ -31,7 +31,7 @@ class PlayerScoredMessage: class PlayerRecord: """Stats for an individual player in a ba.Stats object. - Category: Gameplay Classes + Category: **Gameplay Classes** This does not necessarily correspond to a ba.Player that is still present (stats may be retained for players that leave @@ -229,7 +229,7 @@ class PlayerRecord: class Stats: """Manages scores and statistics for a ba.Session. - Category: Gameplay Classes + Category: **Gameplay Classes** """ def __init__(self) -> None: diff --git a/assets/src/ba_data/python/ba/_team.py b/assets/src/ba_data/python/ba/_team.py index 0cdfbe75..170b62af 100644 --- a/assets/src/ba_data/python/ba/_team.py +++ b/assets/src/ba_data/python/ba/_team.py @@ -17,39 +17,32 @@ if TYPE_CHECKING: class SessionTeam: """A team of one or more ba.SessionPlayers. - Category: Gameplay Classes + Category: **Gameplay Classes** Note that a SessionPlayer *always* has a SessionTeam; in some cases, such as free-for-all ba.Sessions, each SessionTeam consists of just one SessionPlayer. - - Attributes: - - name - The team's name. - - id - The unique numeric id of the team. - - color - The team's color. - - players - The list of ba.SessionPlayers on the team. - - customdata - A dict for use by the current ba.Session for - storing data associated with this team. - Unlike customdata, this persists for the duration - of the session. """ # Annotate our attr types at the class level so they're introspectable. + name: Union[ba.Lstr, str] + """The team's name.""" + color: tuple[float, ...] # FIXME: can't we make this fixed len? + """The team's color.""" + players: list[ba.SessionPlayer] + """The list of ba.SessionPlayer-s on the team.""" + customdata: dict + """A dict for use by the current ba.Session for + storing data associated with this team. + Unlike customdata, this persists for the duration + of the session.""" + id: int + """The unique numeric id of the team.""" def __init__(self, team_id: int = 0, @@ -79,7 +72,7 @@ PlayerType = TypeVar('PlayerType', bound='ba.Player') class Team(Generic[PlayerType]): """A team in a specific ba.Activity. - Category: Gameplay Classes + Category: **Gameplay Classes** These correspond to ba.SessionTeam objects, but are created per activity so that the activity can use its own custom team subclass. @@ -197,7 +190,7 @@ class Team(Generic[PlayerType]): class EmptyTeam(Team['ba.EmptyPlayer']): """An empty player for use by Activities that don't need to define one. - Category: Gameplay Classes + Category: **Gameplay Classes** ba.Player and ba.Team are 'Generic' types, and so passing those top level classes as type arguments when defining a ba.Activity reduces type safety. diff --git a/assets/src/ba_data/python/ba/_teamgame.py b/assets/src/ba_data/python/ba/_teamgame.py index 93076210..a2bc794d 100644 --- a/assets/src/ba_data/python/ba/_teamgame.py +++ b/assets/src/ba_data/python/ba/_teamgame.py @@ -24,7 +24,7 @@ TeamType = TypeVar('TeamType', bound='ba.Team') class TeamGameActivity(GameActivity[PlayerType, TeamType]): """Base class for teams and free-for-all mode games. - Category: Gameplay Classes + Category: **Gameplay Classes** (Free-for-all is essentially just a special case where every ba.Player has their own ba.Team) diff --git a/assets/src/ba_data/python/ba/_ui.py b/assets/src/ba_data/python/ba/_ui.py index bf019471..06298010 100644 --- a/assets/src/ba_data/python/ba/_ui.py +++ b/assets/src/ba_data/python/ba/_ui.py @@ -18,7 +18,7 @@ if TYPE_CHECKING: class UISubsystem: """Consolidated UI functionality for the app. - Category: App Classes + Category: **App Classes** To use this class, access the single instance of it at 'ba.app.ui'. """ diff --git a/assets/src/ba_data/python/bastd/actor/bomb.py b/assets/src/ba_data/python/bastd/actor/bomb.py index ebfc9f01..ae710e94 100644 --- a/assets/src/ba_data/python/bastd/actor/bomb.py +++ b/assets/src/ba_data/python/bastd/actor/bomb.py @@ -22,112 +22,110 @@ PlayerType = TypeVar('PlayerType', bound='ba.Player') class BombFactory: """Wraps up media and other resources used by ba.Bombs. - category: Gameplay Classes + Category: **Gameplay Classes** A single instance of this is shared between all bombs and can be retrieved via bastd.actor.bomb.get_factory(). - - Attributes: - - bomb_model: ba.Model - The ba.Model of a standard or ice bomb. - - sticky_bomb_model: ba.Model - The ba.Model of a sticky-bomb. - - impact_bomb_model: ba.Model - The ba.Model of an impact-bomb. - - land_mine_model: ba.Model - The ba.Model of a land-mine. - - tnt_model: ba.Model - The ba.Model of a tnt box. - - regular_tex: ba.Texture - The ba.Texture for regular bombs. - - ice_tex: ba.Texture - The ba.Texture for ice bombs. - - sticky_tex: ba.Texture - The ba.Texture for sticky bombs. - - impact_tex: ba.Texture - The ba.Texture for impact bombs. - - impact_lit_tex: ba.Texture - The ba.Texture for impact bombs with lights lit. - - land_mine_tex: ba.Texture - The ba.Texture for land-mines. - - land_mine_lit_tex: ba.Texture - The ba.Texture for land-mines with the light lit. - - tnt_tex: ba.Texture - The ba.Texture for tnt boxes. - - hiss_sound: ba.Sound - The ba.Sound for the hiss sound an ice bomb makes. - - debris_fall_sound: ba.Sound - The ba.Sound for random falling debris after an explosion. - - wood_debris_fall_sound: ba.Sound - A ba.Sound for random wood debris falling after an explosion. - - explode_sounds: Sequence[ba.Sound] - A tuple of ba.Sound-s for explosions. - - freeze_sound: ba.Sound - A ba.Sound of an ice bomb freezing something. - - fuse_sound: ba.Sound - A ba.Sound of a burning fuse. - - activate_sound: ba.Sound - A ba.Sound for an activating impact bomb. - - warn_sound: ba.Sound - A ba.Sound for an impact bomb about to explode due to time-out. - - bomb_material: ba.Material - A ba.Material applied to all bombs. - - normal_sound_material: ba.Material - A ba.Material that generates standard bomb noises on impacts, etc. - - sticky_material: ba.Material - A ba.Material that makes 'splat' sounds and makes collisions softer. - - land_mine_no_explode_material: ba.Material - A ba.Material that keeps land-mines from blowing up. - Applied to land-mines when they are created to allow land-mines to - touch without exploding. - - land_mine_blast_material: ba.Material - A ba.Material applied to activated land-mines that causes them to - explode on impact. - - impact_blast_material: ba.Material - A ba.Material applied to activated impact-bombs that causes them to - explode on impact. - - blast_material: ba.Material - A ba.Material applied to bomb blast geometry which triggers impact - events with what it touches. - - dink_sounds: Sequence[ba.Sound] - A tuple of ba.Sound-s for when bombs hit the ground. - - sticky_impact_sound: ba.Sound - The ba.Sound for a squish made by a sticky bomb hitting something. - - roll_sound: ba.Sound - ba.Sound for a rolling bomb. """ + bomb_model: ba.Model + """The ba.Model of a standard or ice bomb.""" + + sticky_bomb_model: ba.Model + """The ba.Model of a sticky-bomb.""" + + impact_bomb_model: ba.Model + """The ba.Model of an impact-bomb.""" + + land_mine_model: ba.Model + """The ba.Model of a land-mine.""" + + tnt_model: ba.Model + """The ba.Model of a tnt box.""" + + regular_tex: ba.Texture + """The ba.Texture for regular bombs.""" + + ice_tex: ba.Texture + """The ba.Texture for ice bombs.""" + + sticky_tex: ba.Texture + """The ba.Texture for sticky bombs.""" + + impact_tex: ba.Texture + """The ba.Texture for impact bombs.""" + + impact_lit_tex: ba.Texture + """The ba.Texture for impact bombs with lights lit.""" + + land_mine_tex: ba.Texture + """The ba.Texture for land-mines.""" + + land_mine_lit_tex: ba.Texture + """The ba.Texture for land-mines with the light lit.""" + + tnt_tex: ba.Texture + """The ba.Texture for tnt boxes.""" + + hiss_sound: ba.Sound + """The ba.Sound for the hiss sound an ice bomb makes.""" + + debris_fall_sound: ba.Sound + """The ba.Sound for random falling debris after an explosion.""" + + wood_debris_fall_sound: ba.Sound + """A ba.Sound for random wood debris falling after an explosion.""" + + explode_sounds: Sequence[ba.Sound] + """A tuple of ba.Sound-s for explosions.""" + + freeze_sound: ba.Sound + """A ba.Sound of an ice bomb freezing something.""" + + fuse_sound: ba.Sound + """A ba.Sound of a burning fuse.""" + + activate_sound: ba.Sound + """A ba.Sound for an activating impact bomb.""" + + warn_sound: ba.Sound + """A ba.Sound for an impact bomb about to explode due to time-out.""" + + bomb_material: ba.Material + """A ba.Material applied to all bombs.""" + + normal_sound_material: ba.Material + """A ba.Material that generates standard bomb noises on impacts, etc.""" + + sticky_material: ba.Material + """A ba.Material that makes 'splat' sounds and makes collisions softer.""" + + land_mine_no_explode_material: ba.Material + """A ba.Material that keeps land-mines from blowing up. + Applied to land-mines when they are created to allow land-mines to + touch without exploding.""" + + land_mine_blast_material: ba.Material + """A ba.Material applied to activated land-mines that causes them to + explode on impact.""" + + impact_blast_material: ba.Material + """A ba.Material applied to activated impact-bombs that causes them to + explode on impact.""" + + blast_material: ba.Material + """A ba.Material applied to bomb blast geometry which triggers impact + events with what it touches.""" + + dink_sounds: Sequence[ba.Sound] + """A tuple of ba.Sound-s for when bombs hit the ground.""" + + sticky_impact_sound: ba.Sound + """The ba.Sound for a squish made by a sticky bomb hitting something.""" + + roll_sound: ba.Sound + """ba.Sound for a rolling bomb.""" + _STORENAME = ba.storagename() @classmethod diff --git a/assets/src/ba_data/python/bastd/actor/flag.py b/assets/src/ba_data/python/bastd/actor/flag.py index 21fafb62..2d7f2133 100644 --- a/assets/src/ba_data/python/bastd/actor/flag.py +++ b/assets/src/ba_data/python/bastd/actor/flag.py @@ -15,38 +15,36 @@ if TYPE_CHECKING: class FlagFactory: - """Wraps up media and other resources used by ba.Flags. + """Wraps up media and other resources used by `Flag`s. - category: Gameplay Classes + Category: **Gameplay Classes** A single instance of this is shared between all flags - and can be retrieved via bastd.actor.flag.get_factory(). - - Attributes: - - flagmaterial: ba.Material - The ba.Material applied to all ba.Flags. - - impact_sound: ba.Sound - The ba.Sound used when a ba.Flag hits the ground. - - skid_sound: ba.Sound - The ba.Sound used when a ba.Flag skids along the ground. - - no_hit_material: ba.Material - A ba.Material that prevents contact with most objects; - applied to 'non-touchable' flags. - - flag_texture: ba.Texture - The ba.Texture for flags. + and can be retrieved via FlagFactory.get(). """ + flagmaterial: ba.Material + """The ba.Material applied to all `Flag`s.""" + + impact_sound: ba.Sound + """The ba.Sound used when a `Flag` hits the ground.""" + + skid_sound: ba.Sound + """The ba.Sound used when a `Flag` skids along the ground.""" + + no_hit_material: ba.Material + """A ba.Material that prevents contact with most objects; + applied to 'non-touchable' flags.""" + + flag_texture: ba.Texture + """The ba.Texture for flags.""" + _STORENAME = ba.storagename() def __init__(self) -> None: - """Instantiate a FlagFactory. + """Instantiate a `FlagFactory`. - You shouldn't need to do this; call bastd.actor.flag.get_factory() to + You shouldn't need to do this; call FlagFactory.get() to get a shared instance. """ shared = SharedObjects.get() @@ -109,7 +107,7 @@ class FlagFactory: @classmethod def get(cls) -> FlagFactory: - """Get/create a shared FlagFactory instance.""" + """Get/create a shared `FlagFactory` instance.""" activity = ba.getactivity() factory = activity.customdata.get(cls._STORENAME) if factory is None: @@ -121,58 +119,47 @@ class FlagFactory: @dataclass class FlagPickedUpMessage: - """A message saying a ba.Flag has been picked up. + """A message saying a `Flag` has been picked up. - category: Message Classes + Category: **Message Classes** + """ - Attributes: - - flag - The ba.Flag that has been picked up. - - node - The ba.Node doing the picking up. - """ flag: Flag + """The `Flag` that has been picked up.""" + node: ba.Node + """The ba.Node doing the picking up.""" @dataclass class FlagDiedMessage: - """A message saying a ba.Flag has died. + """A message saying a `Flag` has died. - category: Message Classes - - Attributes: - - flag - The ba.Flag that died. + Category: **Message Classes** """ + flag: Flag + """The `Flag` that died.""" @dataclass class FlagDroppedMessage: - """A message saying a ba.Flag has been dropped. + """A message saying a `Flag` has been dropped. - category: Message Classes - - Attributes: - - flag - The ba.Flag that was dropped. - - node - The ba.Node that was holding it. + Category: **Message Classes** """ + flag: Flag + """The `Flag` that was dropped.""" + node: ba.Node + """The ba.Node that was holding it.""" class Flag(ba.Actor): """A flag; used in games such as capture-the-flag or king-of-the-hill. - category: Gameplay Classes + Category: **Gameplay Classes** Can be stationary or carry-able by players. """ @@ -189,7 +176,7 @@ class Flag(ba.Actor): useful for things like king-of-the-hill where players should not be moving the flag around. - 'materials can be a list of extra ba.Material-s to apply to the flag. + 'materials can be a list of extra `ba.Material`s to apply to the flag. If 'dropped_timeout' is provided (in seconds), the flag will die after remaining untouched for that long once it has been moved @@ -262,8 +249,8 @@ class Flag(ba.Actor): if not self._has_moved: nodepos = self.node.position if (max( - abs(nodepos[i] - self._initial_position[i]) - for i in list(range(3))) > 1.0): + abs(nodepos[i] - self._initial_position[i]) + for i in list(range(3))) > 1.0): self._has_moved = True if self._held_count > 0 or not self._has_moved: diff --git a/assets/src/ba_data/python/bastd/actor/playerspaz.py b/assets/src/ba_data/python/bastd/actor/playerspaz.py index 6cc762e7..29b535ac 100644 --- a/assets/src/ba_data/python/bastd/actor/playerspaz.py +++ b/assets/src/ba_data/python/bastd/actor/playerspaz.py @@ -17,31 +17,29 @@ TeamType = TypeVar('TeamType', bound=ba.Team) class PlayerSpazHurtMessage: - """A message saying a ba.PlayerSpaz was hurt. + """A message saying a PlayerSpaz was hurt. - category: Message Classes - - Attributes: - - spaz: ba.PlayerSpaz - The ba.PlayerSpaz that was hurt + Category: **Message Classes** """ + spaz: PlayerSpaz + """The PlayerSpaz that was hurt""" + def __init__(self, spaz: PlayerSpaz): """Instantiate with the given ba.Spaz value.""" self.spaz = spaz class PlayerSpaz(Spaz): - """A ba.Spaz subclass meant to be controlled by a ba.Player. + """A Spaz subclass meant to be controlled by a ba.Player. - category: Gameplay Classes + Category: **Gameplay Classes** When a PlayerSpaz dies, it delivers a ba.PlayerDiedMessage to the current ba.Activity. (unless the death was the result of the player leaving the game, in which case no message is sent) - When a PlayerSpaz is hurt, it delivers a ba.PlayerSpazHurtMessage + When a PlayerSpaz is hurt, it delivers a PlayerSpazHurtMessage to the current ba.Activity. """ diff --git a/assets/src/ba_data/python/bastd/actor/powerupbox.py b/assets/src/ba_data/python/bastd/actor/powerupbox.py index 3dda1d9a..cfd51e1d 100644 --- a/assets/src/ba_data/python/bastd/actor/powerupbox.py +++ b/assets/src/ba_data/python/bastd/actor/powerupbox.py @@ -23,69 +23,67 @@ class _TouchedMessage: class PowerupBoxFactory: """A collection of media and other resources used by ba.Powerups. - category: Gameplay Classes + Category: **Gameplay Classes** A single instance of this is shared between all powerups and can be retrieved via ba.Powerup.get_factory(). - - Attributes: - - model: ba.Model - The ba.Model of the powerup box. - - model_simple: ba.Model - A simpler ba.Model of the powerup box, for use in shadows, etc. - - tex_bomb: ba.Texture - Triple-bomb powerup ba.Texture. - - tex_punch: ba.Texture - Punch powerup ba.Texture. - - tex_ice_bombs: ba.Texture - Ice bomb powerup ba.Texture. - - tex_sticky_bombs: ba.Texture - Sticky bomb powerup ba.Texture. - - tex_shield: ba.Texture - Shield powerup ba.Texture. - - tex_impact_bombs: ba.Texture - Impact-bomb powerup ba.Texture. - - tex_health: ba.Texture - Health powerup ba.Texture. - - tex_land_mines: ba.Texture - Land-mine powerup ba.Texture. - - tex_curse: ba.Texture - Curse powerup ba.Texture. - - health_powerup_sound: ba.Sound - ba.Sound played when a health powerup is accepted. - - powerup_sound: ba.Sound - ba.Sound played when a powerup is accepted. - - powerdown_sound: ba.Sound - ba.Sound that can be used when powerups wear off. - - powerup_material: ba.Material - ba.Material applied to powerup boxes. - - powerup_accept_material: ba.Material - Powerups will send a ba.PowerupMessage to anything they touch - that has this ba.Material applied. """ + model: ba.Model + """The ba.Model of the powerup box.""" + + model_simple: ba.Model + """A simpler ba.Model of the powerup box, for use in shadows, etc.""" + + tex_bomb: ba.Texture + """Triple-bomb powerup ba.Texture.""" + + tex_punch: ba.Texture + """Punch powerup ba.Texture.""" + + tex_ice_bombs: ba.Texture + """Ice bomb powerup ba.Texture.""" + + tex_sticky_bombs: ba.Texture + """Sticky bomb powerup ba.Texture.""" + + tex_shield: ba.Texture + """Shield powerup ba.Texture.""" + + tex_impact_bombs: ba.Texture + """Impact-bomb powerup ba.Texture.""" + + tex_health: ba.Texture + """Health powerup ba.Texture.""" + + tex_land_mines: ba.Texture + """Land-mine powerup ba.Texture.""" + + tex_curse: ba.Texture + """Curse powerup ba.Texture.""" + + health_powerup_sound: ba.Sound + """ba.Sound played when a health powerup is accepted.""" + + powerup_sound: ba.Sound + """ba.Sound played when a powerup is accepted.""" + + powerdown_sound: ba.Sound + """ba.Sound that can be used when powerups wear off.""" + + powerup_material: ba.Material + """ba.Material applied to powerup boxes.""" + + powerup_accept_material: ba.Material + """Powerups will send a ba.PowerupMessage to anything they touch + that has this ba.Material applied.""" + _STORENAME = ba.storagename() def __init__(self) -> None: """Instantiate a PowerupBoxFactory. - You shouldn't need to do this; call ba.Powerup.get_factory() + You shouldn't need to do this; call Powerup.get_factory() to get a shared instance. """ from ba.internal import get_default_powerup_distribution @@ -191,18 +189,16 @@ class PowerupBox(ba.Actor): This will deliver a ba.PowerupMessage to anything that touches it which has the ba.PowerupBoxFactory.powerup_accept_material applied. - - Attributes: - - poweruptype: str - The string powerup type. This can be 'triple_bombs', 'punch', - 'ice_bombs', 'impact_bombs', 'land_mines', 'sticky_bombs', 'shield', - 'health', or 'curse'. - - node: ba.Node - The 'prop' ba.Node representing this box. """ + poweruptype: str + """The string powerup type. This can be 'triple_bombs', 'punch', + 'ice_bombs', 'impact_bombs', 'land_mines', 'sticky_bombs', 'shield', + 'health', or 'curse'.""" + + node: ba.Node + """The 'prop' ba.Node representing this box.""" + def __init__(self, position: Sequence[float] = (0.0, 1.0, 0.0), poweruptype: str = 'triple_bombs', diff --git a/assets/src/ba_data/python/bastd/actor/spawner.py b/assets/src/ba_data/python/bastd/actor/spawner.py index b1ed9c11..16693bd7 100644 --- a/assets/src/ba_data/python/bastd/actor/spawner.py +++ b/assets/src/ba_data/python/bastd/actor/spawner.py @@ -16,29 +16,27 @@ if TYPE_CHECKING: class Spawner: """Utility for delayed spawning of objects. - category: Gameplay Classes + Category: **Gameplay Classes** - Creates a light flash and sends a ba.Spawner.SpawnMessage + Creates a light flash and sends a Spawner.SpawnMessage to the current activity after a delay. """ class SpawnMessage: - """Spawn message sent by a ba.Spawner after its delay has passed. + """Spawn message sent by a Spawner after its delay has passed. - category: Message Classes - - Attributes: - - spawner - The ba.Spawner we came from. - - data - The data object passed by the user. - - pt - The spawn position. + Category: **Message Classes** """ + spawner: Spawner + """The ba.Spawner we came from.""" + + data: Any + """The data object passed by the user.""" + + pt: Sequence[float] + """The spawn position.""" + def __init__( self, spawner: Spawner, diff --git a/assets/src/ba_data/python/bastd/actor/spaz.py b/assets/src/ba_data/python/bastd/actor/spaz.py index 37ab09e9..b6101ea8 100644 --- a/assets/src/ba_data/python/bastd/actor/spaz.py +++ b/assets/src/ba_data/python/bastd/actor/spaz.py @@ -42,23 +42,21 @@ class Spaz(ba.Actor): """ Base class for various Spazzes. - category: Gameplay Classes + Category: **Gameplay Classes** A Spaz is the standard little humanoid character in the game. It can be controlled by a player or by AI, and can have various different appearances. The name 'Spaz' is not to be confused with the 'Spaz' character in the game, which is just one of the skins available for instances of this class. - - Attributes: - - node: ba.Node - The 'spaz' ba.Node. """ # pylint: disable=too-many-public-methods # pylint: disable=too-many-locals + node: ba.Node + """The 'spaz' ba.Node.""" + points_mult = 1 curse_time: Optional[float] = 5.0 default_bomb_count = 1 diff --git a/assets/src/ba_data/python/bastd/actor/spazbot.py b/assets/src/ba_data/python/bastd/actor/spazbot.py index e225962f..62b012cd 100644 --- a/assets/src/ba_data/python/bastd/actor/spazbot.py +++ b/assets/src/ba_data/python/bastd/actor/spazbot.py @@ -27,17 +27,15 @@ PRO_BOT_HIGHLIGHT = (0.6, 0.1, 0.05) class SpazBotPunchedMessage: """A message saying a ba.SpazBot got punched. - category: Message Classes - - Attributes: - - spazbot: ba.SpazBot - The ba.SpazBot that got punched. - - damage: int - How much damage was done to the ba.SpazBot. + Category: **Message Classes** """ + spazbot: SpazBot + """The ba.SpazBot that got punched.""" + + damage: int + """How much damage was done to the SpazBot.""" + def __init__(self, spazbot: SpazBot, damage: int): """Instantiate a message with the given values.""" self.spazbot = spazbot @@ -47,20 +45,18 @@ class SpazBotPunchedMessage: class SpazBotDiedMessage: """A message saying a ba.SpazBot has died. - category: Message Classes - - Attributes: - - spazbot: ba.SpazBot - The ba.SpazBot that was killed. - - killerplayer: ba.Player - The ba.Player that killed it (or None). - - how: ba.DeathType - The particular type of death. + Category: **Message Classes** """ + spazbot: SpazBot + """The SpazBot that was killed.""" + + killerplayer: ba.Player + """The ba.Player that killed it (or None).""" + + how: ba.DeathType + """The particular type of death.""" + def __init__(self, spazbot: SpazBot, killerplayer: Optional[ba.Player], how: ba.DeathType): """Instantiate with given values.""" @@ -72,7 +68,7 @@ class SpazBotDiedMessage: class SpazBot(Spaz): """A really dumb AI version of ba.Spaz. - category: Bot Classes + Category: **Bot Classes** Add these to a ba.BotSet to use them. diff --git a/assets/src/ba_data/python/bastd/actor/spazfactory.py b/assets/src/ba_data/python/bastd/actor/spazfactory.py index 128d3098..1a5bb9be 100644 --- a/assets/src/ba_data/python/bastd/actor/spazfactory.py +++ b/assets/src/ba_data/python/bastd/actor/spazfactory.py @@ -11,72 +11,70 @@ from bastd.gameutils import SharedObjects import _ba if TYPE_CHECKING: - from typing import Any + from typing import Any, Sequence class SpazFactory: """Wraps up media and other resources used by ba.Spaz instances. - Category: Gameplay Classes + Category: **Gameplay Classes** Generally one of these is created per ba.Activity and shared - between all spaz instances. Use ba.Spaz.get_factory() to return + between all spaz instances. Use ba.Spaz.get_factory() to return the shared factory for the current activity. - - Attributes: - - impact_sounds_medium: Sequence[ba.Sound] - A tuple of ba.Sound-s for when a ba.Spaz hits something kinda hard. - - impact_sounds_hard: Sequence[ba.Sound] - A tuple of ba.Sound-s for when a ba.Spaz hits something really hard. - - impact_sounds_harder: Sequence[ba.Sound] - A tuple of ba.Sound-s for when a ba.Spaz hits something really - really hard. - - single_player_death_sound: ba.Sound - The sound that plays for an 'important' spaz death such as in - co-op games. - - punch_sound: ba.Sound - A standard punch ba.Sound. - - punch_sound_strong: Sequence[ba.Sound] - A tuple of stronger sounding punch ba.Sounds. - - punch_sound_stronger: ba.Sound - A really really strong sounding punch ba.Sound. - - swish_sound: ba.Sound - A punch swish ba.Sound. - - block_sound: ba.Sound - A ba.Sound for when an attack is blocked by invincibility. - - shatter_sound: ba.Sound - A ba.Sound for when a frozen ba.Spaz shatters. - - splatter_sound: ba.Sound - A ba.Sound for when a ba.Spaz blows up via curse. - - spaz_material: ba.Material - A ba.Material applied to all of parts of a ba.Spaz. - - roller_material: ba.Material - A ba.Material applied to the invisible roller ball body that - a ba.Spaz uses for locomotion. - - punch_material: ba.Material - A ba.Material applied to the 'fist' of a ba.Spaz. - - pickup_material: ba.Material - A ba.Material applied to the 'grabber' body of a ba.Spaz. - - curse_material: ba.Material - A ba.Material applied to a cursed ba.Spaz that triggers an explosion. """ + impact_sounds_medium: Sequence[ba.Sound] + """A tuple of ba.Sound-s for when a ba.Spaz hits something kinda hard.""" + + impact_sounds_hard: Sequence[ba.Sound] + """A tuple of ba.Sound-s for when a ba.Spaz hits something really hard.""" + + impact_sounds_harder: Sequence[ba.Sound] + """A tuple of ba.Sound-s for when a ba.Spaz hits something really + really hard.""" + + single_player_death_sound: ba.Sound + """The sound that plays for an 'important' spaz death such as in + co-op games.""" + + punch_sound: ba.Sound + """A standard punch ba.Sound.""" + + punch_sound_strong: Sequence[ba.Sound] + """A tuple of stronger sounding punch ba.Sounds.""" + + punch_sound_stronger: ba.Sound + """A really really strong sounding punch ba.Sound.""" + + swish_sound: ba.Sound + """A punch swish ba.Sound.""" + + block_sound: ba.Sound + """A ba.Sound for when an attack is blocked by invincibility.""" + + shatter_sound: ba.Sound + """A ba.Sound for when a frozen ba.Spaz shatters.""" + + splatter_sound: ba.Sound + """A ba.Sound for when a ba.Spaz blows up via curse.""" + + spaz_material: ba.Material + """A ba.Material applied to all of parts of a ba.Spaz.""" + + roller_material: ba.Material + """A ba.Material applied to the invisible roller ball body that + a ba.Spaz uses for locomotion.""" + + punch_material: ba.Material + """A ba.Material applied to the 'fist' of a ba.Spaz.""" + + pickup_material: ba.Material + """A ba.Material applied to the 'grabber' body of a ba.Spaz.""" + + curse_material: ba.Material + """A ba.Material applied to a cursed ba.Spaz that triggers an explosion.""" + _STORENAME = ba.storagename() def _preload(self, character: str) -> None: diff --git a/assets/src/ba_data/python/bastd/ui/config.py b/assets/src/ba_data/python/bastd/ui/config.py index b9e74000..d8567e51 100644 --- a/assets/src/ba_data/python/bastd/ui/config.py +++ b/assets/src/ba_data/python/bastd/ui/config.py @@ -17,13 +17,11 @@ class ConfigCheckBox: It will automatically save and apply the config when its value changes. - - Attributes: - - widget - The underlying ba.Widget instance. """ + widget: ba.Widget + """The underlying ba.Widget instance.""" + def __init__(self, parent: ba.Widget, configkey: str, @@ -65,22 +63,20 @@ class ConfigNumberEdit: It will automatically save and apply the config when its value changes. - - Attributes: - - nametext - The text widget displaying the name. - - valuetext - The text widget displaying the current value. - - minusbutton - The button widget used to reduce the value. - - plusbutton - The button widget used to increase the value. """ + nametext: ba.Widget + """The text widget displaying the name.""" + + valuetext: ba.Widget + """The text widget displaying the current value.""" + + minusbutton: ba.Widget + """The button widget used to reduce the value.""" + + plusbutton: ba.Widget + """The button widget used to increase the value.""" + def __init__(self, parent: ba.Widget, configkey: str, diff --git a/src/ballistica/python/class/python_class_collide_model.cc b/src/ballistica/python/class/python_class_collide_model.cc index 71b3237c..b66764db 100644 --- a/src/ballistica/python/class/python_class_collide_model.cc +++ b/src/ballistica/python/class/python_class_collide_model.cc @@ -27,7 +27,7 @@ void PythonClassCollideModel::SetupType(PyTypeObject* obj) { "\n" "Category: **Asset Classes**\n" "\n" - "Use ba.getcollidemodel to instantiate one."; + "Use ba.getcollidemodel() to instantiate one."; obj->tp_repr = (reprfunc)tp_repr; obj->tp_new = tp_new; obj->tp_dealloc = (destructor)tp_dealloc; diff --git a/src/ballistica/python/class/python_class_context.cc b/src/ballistica/python/class/python_class_context.cc index 2948c930..9df99fb1 100644 --- a/src/ballistica/python/class/python_class_context.cc +++ b/src/ballistica/python/class/python_class_context.cc @@ -21,7 +21,7 @@ void PythonClassContext::SetupType(PyTypeObject* obj) { "\n" "Category: **General Utility Classes**\n" "\n" - "Many operations such as ba.newnode or ba.gettexture operate\n" + "Many operations such as ba.newnode() or ba.gettexture() operate\n" "implicitly on the current context. Each ba.Activity has its own\n" "Context and objects within that activity (nodes, media, etc) can only\n" "interact with other objects from that context.\n" @@ -36,7 +36,7 @@ void PythonClassContext::SetupType(PyTypeObject* obj) { "When instantiating a ba.Context instance, a single `'source'` " "argument\n" "is passed, which can be one of the following strings/objects:\n\n" - "`'empty'`:\n" + "###### `'empty'`\n" "> Gives an empty context; it can be handy to run code here to ensure\n" "it does no loading of media, creation of nodes, etc.\n" "\n" diff --git a/src/ballistica/python/class/python_class_data.cc b/src/ballistica/python/class/python_class_data.cc index eb27df33..2e37a415 100644 --- a/src/ballistica/python/class/python_class_data.cc +++ b/src/ballistica/python/class/python_class_data.cc @@ -26,7 +26,7 @@ void PythonClassData::SetupType(PyTypeObject* obj) { "\n" "Category: **Asset Classes**\n" "\n" - "Use ba.getdata to instantiate one."; + "Use ba.getdata() to instantiate one."; obj->tp_repr = (reprfunc)tp_repr; obj->tp_new = tp_new; obj->tp_dealloc = (destructor)tp_dealloc; diff --git a/src/ballistica/python/class/python_class_material.cc b/src/ballistica/python/class/python_class_material.cc index f5d651e5..8de56cbd 100644 --- a/src/ballistica/python/class/python_class_material.cc +++ b/src/ballistica/python/class/python_class_material.cc @@ -51,21 +51,21 @@ void PythonClassMaterial::SetupType(PyTypeObject* obj) { "\n" "An entity applied to game objects to modify collision behavior.\n" "\n" - "Category: Gameplay Classes\n" + "Category: **Gameplay Classes**\n" "\n" "A material can affect physical characteristics, generate sounds,\n" "or trigger callback functions when collisions occur.\n" "\n" - "Materials are applied to ``'parts'``, which are groups of one or more\n" + "Materials are applied to 'parts', which are groups of one or more\n" "rigid bodies created as part of a ba.Node. Nodes can have any number\n" "of parts, each with its own set of materials. Generally materials are\n" - "specified as array attributes on the Node. The ``'spaz'`` node, for\n" - "example, has various attributes such as ``'materials'``,\n" - "``'roller_materials'``, and ``'punch_materials'``, which correspond\n" + "specified as array attributes on the Node. The `spaz` node, for\n" + "example, has various attributes such as `materials`,\n" + "`roller_materials`, and `punch_materials`, which correspond\n" "to the various parts it creates.\n" "\n" "Use ba.Material to instantiate a blank material, and then use its\n" - "ba.Material.add_actions method to define what the material does.\n" + "ba.Material.add_actions() method to define what the material does.\n" "\n" "Attributes:\n" "\n" @@ -342,7 +342,7 @@ PyMethodDef PythonClassMaterial::tp_methods[] = { "`'at_connect'` or `'at_disconnect'`, and `message_obj` is the message\n" "object to send.\n" "This has the same effect as calling the node's\n" - "ba.Node.handlemessage method.\n" + "ba.Node.handlemessage() method.\n" "\n" "###### `('modify_part_collision', attr, value)`\n" "> Changes some\n" @@ -362,7 +362,7 @@ PyMethodDef PythonClassMaterial::tp_methods[] = { "overrides for this collision), `'stiffness'` (float value,\n" "how springy the physical response is), `'damping'` (float\n" "value, how damped the physical response is), `'bounce'` (float\n" - "value; how bouncy the physical response is)." + "value; how bouncy the physical response is).\n" "\n" "###### `('modify_node_collision', attr, value)`\n" "> Similar to\n" @@ -410,7 +410,6 @@ PyMethodDef PythonClassMaterial::tp_methods[] = { "\n" "**Example 2:** send a ba.DieMessage to anything we touch, but cause\n" "no physical response. This should cause any ba.Actor to drop dead:\n" - "```python\n" ">>> m = ba.Material()\n" "... m.add_actions(\n" "... actions=(('modify_part_collision', 'physical', False),\n" @@ -418,7 +417,6 @@ PyMethodDef PythonClassMaterial::tp_methods[] = { "... ba.DieMessage())))\n" "\n" "**Example 3:** play some sounds when we're contacting the ground:\n" - "```python\n" ">>> m = ba.Material()\n" "... m.add_actions(\n" "... conditions=('they_have_material',\n" diff --git a/src/ballistica/python/class/python_class_node.cc b/src/ballistica/python/class/python_class_node.cc index 684b7891..751a17a6 100644 --- a/src/ballistica/python/class/python_class_node.cc +++ b/src/ballistica/python/class/python_class_node.cc @@ -25,7 +25,7 @@ void PythonClassNode::SetupType(PyTypeObject* obj) { obj->tp_doc = "Reference to a Node; the low level building block of the game.\n" "\n" - "Category: Gameplay Classes\n" + "Category: **Gameplay Classes**\n" "\n" "At its core, a game is nothing more than a scene of Nodes\n" "with attributes getting interconnected or set over time.\n" @@ -34,8 +34,8 @@ void PythonClassNode::SetupType(PyTypeObject* obj) { "to a game node; *not* the node itself. This means a Node's\n" "lifecycle is completely independent of how many Python references\n" "to it exist. To explicitly add a new node to the game, use\n" - "ba.newnode, and to explicitly delete one, use ba.Node.delete.\n" - "ba.Node.exists can be used to determine if a Node still points to\n" + "ba.newnode(), and to explicitly delete one, use ba.Node.delete().\n" + "ba.Node.exists() can be used to determine if a Node still points to\n" "a live node in the game.\n" "\n" "You can use ba.Node(None) to instantiate an invalid\n" diff --git a/src/ballistica/python/class/python_class_session_player.cc b/src/ballistica/python/class/python_class_session_player.cc index 8f914a77..7dd71794 100644 --- a/src/ballistica/python/class/python_class_session_player.cc +++ b/src/ballistica/python/class/python_class_session_player.cc @@ -53,7 +53,7 @@ void PythonClassSessionPlayer::SetupType(PyTypeObject* obj) { "Be aware that, like ba.Nodes, ba.SessionPlayer objects are 'weak'\n" "references under-the-hood; a player can leave the game at\n" " any point. For this reason, you should make judicious use of the\n" - "ba.SessionPlayer.exists method (or boolean operator) to ensure\n" + "ba.SessionPlayer.exists() method (or boolean operator) to ensure\n" "that a SessionPlayer is still present if retaining references to one\n" "for any length of time.\n" "\n" diff --git a/src/ballistica/python/class/python_class_sound.cc b/src/ballistica/python/class/python_class_sound.cc index 52a58545..ba6b5732 100644 --- a/src/ballistica/python/class/python_class_sound.cc +++ b/src/ballistica/python/class/python_class_sound.cc @@ -26,7 +26,7 @@ void PythonClassSound::SetupType(PyTypeObject* obj) { "\n" "Category: **Asset Classes**\n" "\n" - "Use ba.getsound to instantiate one."; + "Use ba.getsound() to instantiate one."; obj->tp_repr = (reprfunc)tp_repr; obj->tp_new = tp_new; obj->tp_dealloc = (destructor)tp_dealloc; diff --git a/src/ballistica/python/class/python_class_widget.cc b/src/ballistica/python/class/python_class_widget.cc index 2008afe2..5311ee6b 100644 --- a/src/ballistica/python/class/python_class_widget.cc +++ b/src/ballistica/python/class/python_class_widget.cc @@ -26,7 +26,7 @@ void PythonClassWidget::SetupType(PyTypeObject* obj) { "\n" "This class represents a weak reference to a widget object\n" "in the internal C++ layer. Currently, functions such as\n" - "ba.buttonwidget must be used to instantiate or edit these."; + "ba.buttonwidget() must be used to instantiate or edit these."; obj->tp_new = tp_new; obj->tp_dealloc = (destructor)tp_dealloc; obj->tp_repr = (reprfunc)tp_repr; diff --git a/src/ballistica/python/methods/python_methods_app.cc b/src/ballistica/python/methods/python_methods_app.cc index b9830b18..51a2d652 100644 --- a/src/ballistica/python/methods/python_methods_app.cc +++ b/src/ballistica/python/methods/python_methods_app.cc @@ -1034,7 +1034,7 @@ auto PythonMethodsApp::GetMethods() -> std::vector { " require the ability to do so, use the ba.Timer class instead.\n" "\n" "##### Arguments\n" - "###### time (float):\n" + "###### time (float)\n" "> Length of time (in seconds by default) that the timer will wait\n" "before firing. Note that the actual delay experienced may vary\n " "depending on the timetype. (see below)\n" diff --git a/src/ballistica/python/methods/python_methods_system.cc b/src/ballistica/python/methods/python_methods_system.cc index 7c46c60f..aa3c28e6 100644 --- a/src/ballistica/python/methods/python_methods_system.cc +++ b/src/ballistica/python/methods/python_methods_system.cc @@ -812,7 +812,7 @@ auto PythonMethodsSystem::GetMethods() -> std::vector { "\n" "Category: **General Utility Functions**\n" "\n" - "Ensure that ba.clipboard_available returns True before adding\n" + "Ensure that ba.clipboard_available() returns True before adding\n" " buttons/etc. that make use of this functionality."}, {"clipboard_get_text", (PyCFunction)PyClipboardGetText, METH_NOARGS, "clipboard_get_text() -> str\n" @@ -821,7 +821,7 @@ auto PythonMethodsSystem::GetMethods() -> std::vector { "\n" "Category: **General Utility Functions**\n" "\n" - "Ensure that ba.clipboard_has_text returns True before calling\n" + "Ensure that ba.clipboard_has_text() returns True before calling\n" " this function."}, {"printobjects", (PyCFunction)PyPrintObjects, METH_VARARGS | METH_KEYWORDS,