{"id":26447537,"url":"https://github.com/z0u/bat","last_synced_at":"2025-03-18T13:57:29.159Z","repository":{"id":12684966,"uuid":"15357134","full_name":"z0u/bat","owner":"z0u","description":"The Blender Adventure Toolkit - helper library for management of objects, sounds, etc.","archived":false,"fork":false,"pushed_at":"2014-05-10T02:10:14.000Z","size":760,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2023-08-07T10:56:42.639Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/z0u.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-12-21T10:09:02.000Z","updated_at":"2014-08-05T11:42:50.000Z","dependencies_parsed_at":"2022-09-23T08:50:54.733Z","dependency_job_id":null,"html_url":"https://github.com/z0u/bat","commit_stats":null,"previous_names":[],"tags_count":0,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/z0u%2Fbat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/z0u%2Fbat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/z0u%2Fbat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/z0u%2Fbat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/z0u","download_url":"https://codeload.github.com/z0u/bat/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244236086,"owners_count":20420753,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-18T13:57:28.421Z","updated_at":"2025-03-18T13:57:29.152Z","avatar_url":"https://github.com/z0u.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Blender Adventure Toolkit\n\nThis is the Blender Adventure Toolkit (*bat*) - a Python library for use with\nthe Blender Game Engine (BGE). *Bat* provides classes and functions that can\nhelp with the creation of games in BGE. It was designed with adventure games in\nmind (hence the `story` module), but it would be useful for any kind of game.\n\nTo use this library, link to `bat_assets.blend` and add the `G_BXT` group to\nyour scene. Then you can use the Python modules from your code, for example:\n\n- Write custom game object classes by inheriting from `bats.BX_GameObject` as a\n  mixin.\n- Send same-frame events between objects using the `event` module.\n- Create story sequences using the `story` module.\n- Respond to animation events using the `anim` module.\n\nModules are described in more detail below.\n\n\n## Object Management\n\n- `bats`: [Metaclasses][mc] for creating extended objects and singletons. This\n  provides a convenient mechanism for subclassing Blender's `KX_GameObject`\n  class, and allows the custom *methods* to be called from logic bricks. The\n  `BX_GameObject` class should be mixed in with `KX_GameObject`,\n  `BL_ArmartureObject` or similar.\n- `containers`: \"Safe\" collections (lists and sets) for storing game objects.\n  If an object is removed from the scene, it will automatically be removed from\n  the list - so you never need to check while iterating.\n- `event`: An event bus for loosely-coupled communication between objects.\n  This is similar to the BGE's messages, but events can be received on the *same\n  frame* or delayed and sent some number of frames in the future.\n- `utils`: Basic object management functions such as:\n    - Get/set states without using bitmasks.\n    - Decorators to make calling functions with owners from logic bricks (or\n      not!) easier.\n\n\n## Story Progression\n\n- `store`: Adds path support to Blender's saved game files. Defines some\n  special paths such as `/game/`, which allows easy IO of saved game data for\n  the current game (in a game that supports multiple saved games).\n- `story`: State machine for describing multi-step story interactions, e.g. conversations. The\n  important thing to note is that this does not happen in one function call;\n  the steps are evaluated over many frames so the game can continue while the\n  state machine runs. Allows the creation of sequences like:\n    1. Play animation X.\n    1. When animation X reaches frame 25, play a sound.\n    1. When the animation finishes, show the user a message and wait for input.\n\n```python\ns = (self.rootState.create_successor('Init')\n    (bat.story.ActAction(\"B_Final\", 1, 60))\n    (bat.story.State()\n        (bat.story.CondActionGE(0, 25, tap=True))\n        (bat.story.ActSound('//Sound/cc-by/BirdSquarkSmall.ogg', pitchmin=0.9, pitchmax=1.1))\n    )\n)\n\ns = (s.create_successor()\n    (bat.story.CondActionGE(0, 60))\n    (\"ShowDialogue\", \"Hi there, little snail! It's nice of you to come to visit.\")\n)\n```\n\nIn the example above, there are three states:\n\n- The first state succeeds from the root state and has no conditions, so it\n  will become active at the start. There is one action that plays an\n  animation (`ActAction`). There is also a sub-state.\n- The sub-state is evaluated for every frame that its parent is active. In\n  this case it has a condition that says it will only run when the animation\n  frame is greater than or equal to `25` (`CondActionGE`). It will only run\n  once, because `tap=True`. It has one action that plays a sound (`ActSound`).\n- The third state succeeds from the first state. It will become active when\n  the animation reaches frame `25` (`CondActionGE`), and at that point the\n  first state will become inactive. It has one action, which is to send an\n  event. Events can be sent using the special syntax `subject, body` - this\n  is a shortcut for the `ActEvent` class.\n\nNote that only one state can be active at a time, and sub-states are never really active.\n\nThe syntax above is made passible by the `State.__call__` method and [chaining][ch].\nIf you don't like it, you can write more explicit code like this:\n\n```python\nssquark = bat.story.State()\nssquark.add_condition(bat.story.CondActionGE(0, 25, tap=True))\nssquark.add_action(bat.story.ActSound('//Sound/cc-by/BirdSquarkSmall.ogg', pitchmin=0.9, pitchmax=1.1))\n\ns = self.rootState.create_successor('Init')\ns.add_action(bat.story.ActAction(\"B_Final\", 1, 60))\ns.add_sub_step(ssquark)\n\ns = s.create_successor()\ns.add_condition(bat.story.CondActionGE(0, 60))\ns.add_event(\"ShowDialogue\", \"Hi there, little snail! It's nice of you to come to visit.\")\n```\n\n[ch]: http://en.wikipedia.org/wiki/Method_chaining\n\n\n## IO\n\n- `impulse`: User input abstraction, allowing run-time configuration of input\n  devices such as keyboards and joysticks. All devices are presented using the\n  same interfaces, e.g. a mouse has two axes just like a joystick. Multiple\n  physical keys and buttons can be bound to the same logical button, e.g. \"Up\"\n  could have bindings `w`, `uparrow`, `joystick axis 1 (positive)` and\n  `joystick dpad 1` simultaneously.\n- `sound`: Enhanced API for playing sounds and layering effects. Includes\n  event-driven music track switching with support for cross-fading - allowing\n  the music to change as your character moves around the level, or when\n  something happens in the story. Music tracks can be given priorities, e.g.\n  music for a battle situation might have a high priority while background music\n  would have a low priority.\n\n\n## Dynamics and Kinematics\n\n- `anim`: Animation utils. Allows registration of callbacks for animations,\n  e.g. run a function when an animation reaches a certain frame.\n- `bmath`: Handy maths functions for interpolation, spatial sorting and ray\n  casting.\n- `c`: Basic dynamic behaviours, such as slow parenting (with proper smooth\n  rotational interpolation), and following at a distance.\n- `effectors`: Force fields that push objects around, e.g. wind and vortices.\n- `render`: Colour conversion and decoding e.g.\n  `white -\u003e #fff -\u003e (1.0, 1.0, 1.0)`\n- `water`: Special shaped force fields (shaped by water surface) implementing\n  basic buoyancy.\n\n\n## Meta\n\n- `debug`: Debugging utilities e.g. pretty printers for console.\n- `statprof`: Statistical profiler for finding hotspots (slow parts) of Python\n  code.\n\n\n\n[mc]: http://stackoverflow.com/a/100146/320036\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fz0u%2Fbat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fz0u%2Fbat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fz0u%2Fbat/lists"}