Package: kivy-okapi
## Okapi#### What it isA library to build grid-based games using Kivy 1.9#### InstallationInstalling packages with Kivy is a joy because you cannot use virtual environments (assuming you use the Kivy package installer). Kivy creates its own unique snowflake environment, then provides a `kivy` command-line utility that heavily modifies your `PYTHONPATH` before ultimately launching the python interpreter. Thus, virtual environments are off the table, as none of their packages can be imported after using `kivy`.1. [Download the Kivy installer](http://kivy.org/docs/installation/installation.html) and use it to install Kivy.2. Next, install `okapi` from PyPI using Kivy's `pip`: `$ kivy -m pip install kivy-okapi`#### Launching an `Okapi` AppOnce `Okapi` is installed where Kivy is willing to look, you can simply navigate into any game folder and run `kivy main.py` like normal, and all Okapi libraries will be available.## Building a Game with `Okapi`For reference, a complete example is provided in the `/examples/rodents_revenge` directory#### Create an `OkapiApp` classIn your `main.py` file, provide this bare minimum skeleton:```py# Okapifrom okapi.app import Okapi as OkapiApp# Localfrom game import Gamefrom screen_manager import ScreenManagerclass MyGameApp(OkapiApp):GAME_CLASS = GameSCREEN_MANAGER_CLS = ScreenManagerPROJECT_PATH = PROJECT_PATHdef get_application_name(self):return "My Game"if __name__ == '__main__':MyGameApp().run()```#### Kivy's `build()` methodThose familiar with Kivy know that the your project's main `App` class is required to define a `build()` function that returns the root widget. For `Okapi`, that root widget is of the `ScreenManager` class. It is this widget's job to swap in and out loading screens, the game screen, menu screens, high score screens, etc.An example of overriding the `ScreenManager` class is provided in the Rodent's Revenge game, but here is a bare minimum example:```py# Okapifrom okapi.screen_manager import ScreenManager as OkapiScreenManager# Localfrom welcome_screen import WelcomeScreenclass ScreenManager(OkapiScreenManager):def get_welcome_screen(self):"""Optional.If implemented, should return a `Screen` widget that says somethinglike "Hello, welcome to my game!" and has a click listener. The`OkapiScreenManager` will listen for that click and start the game."""return WelcomeScreen()def get_screen_from_game(self):"""Required.Should do something with `self.game` to get a Screen widget used to startand render the game."""return self.game.get_screen()```#### Listening to Kivy's clockThe `ScreenManager` is also a clean interface to Kivy's clock module. Your `ScreenManager` keeps track of a `current_screen` attribute,and whenever this changes it unregisters any clock listeners from the previous screen and registers the new screen's clock listeners.To register clock handlers, define them like so:```py# Okapifrom okapi.screen import Screenclass SomeScreen(Screen):def every_second(self):# Do stuffdef every_other_second(self):# Do more stuffdef get_clock_tuple(self):# Option 1return (self.every_second, 1.0,)# or Option 2return ((self.every_second, 1.0,),(self.every_other_second, 2.0,),)```The `ScreenManager` class will also drill down and check all top-level children of a screen to see if any have clock listeners.#### Listening to keyboard inputThe `ScreenManager` also listens to all keyboard input and passes it to both `self.game` and whatever is its `current_screen`. To listen for clicks to the "down arrow":```py# Okapifrom okapi.screen import Screenclass SomeScreen(Screen):def on_press_down(self):# Do stuffdef on_press_y(self):# Do stuffdef on_press_cmd_w(self):# Do stuffdef on_press_alt_shift_s(self):# Do stuff```The above definitions also apply to your `Game` class.If there are > 1 modifier keys pressed (`shift`, `command`, `alt`, etc) they will be alphabetized for consistency.#### The `Game` classThe `Game` class is where you put your fun game logic! Define one like so:```py# Enginefrom okapi.engine.game import Game as OkapiGameclass Game(OkapiGame):# Used by `OkapiGame` to provide default functionality for# `self.get_clock_tuple()`# Rodent's Revenge only has to update once per secondCLOCK_INTERVAL = 1.0# Default blank ground -- empty walkable spaceBLANK_GROUND_CHARACTER = '.'# Other special types of ground. Maybe impassable, or maybe# containing various actorsEXTRA_GROUNDS = {"b": ground.BlockGround,"#": ground.ImpassableGround,}def clock_update(self, dt):# Make the game happen!def on_press_down(self):# Move something down!```#### Moving actorsThe `OkapiGame` class provides a function called `move_actor`. Let's say you are building a chess app. To move a knight, you would make a call like this:```pyself.game.move_actor(self.white_knight_1, 1, 2)```This will immediately cause a reanimation, showing the white knight having just moved.#### Moving RulesMoving legality is determined by the target ground's `can_accommodate()` method. By default, this rejects movements into occupied territory. Of course, that rule makes little sense for chess, so for that example you'd want to override that function to accept new pieces at any time, and to remove from the game any piece currently found in that spot.