1""".. include:: ../README.md
  2
  3# Install
  4```bash
  5pip install git+https://github.com/ArielHorwitz/mousefox.git
  6```
  7
  8# Built-in examples
  9Tic-tac-toe:
 10```python3
 11import mousefox
 12
 13mousefox.examples.tictactoe()
 14```
 15
 16Text chat:
 17```python3
 18import mousefox
 19
 20mousefox.examples.chat()
 21```
 22
 23# Getting started
 24When working with MouseFox, we will become familiar with
 25[PGNet](https://github.com/ArielHorwitz/pgnet) and [Kivy](https://kivy.org/doc/stable/).
 26Let's walk through making a simple multiplayer clicker game.
 27
 28## Game logic
 29We require a `pgnet.Game` class. This class will be initialized by the server whenever a
 30user creates a new game:
 31```python3
 32import pgnet
 33
 34class ClickerGame(pgnet.Game):
 35    clicks = 0
 36
 37    def handle_heartbeat(self, packet: pgnet.Packet) -> pgnet.Response:
 38        # Return game updates
 39        message = f"Number of clicks: {self.clicks}"
 40        return pgnet.Response(message)
 41
 42    def handle_game_packet(self, packet: pgnet.Packet) -> pgnet.Response:
 43        # Handle requests and actions
 44        self.clicks += 1
 45        return pgnet.Response("Clicked.")
 46```
 47
 48## Game widget
 49We require a Kivy `Widget` class. This class will be initialized by the GUI whenever the
 50user joins a game.
 51```python3
 52from kivy.uix.label import Label
 53import pgnet
 54
 55class ClickerWidget(Label):
 56    def __init__(self, client: pgnet.Client):
 57        # Init the kivy widget and bind to client heartbeat
 58        super().__init__(text="Waiting for data from server...")
 59        self.client = client
 60        self.client.on_heartbeat = self.on_heartbeat
 61
 62    def on_heartbeat(self, heartbeat: pgnet.Response):
 63        # Use heartbeat to get game updates
 64        self.text = heartbeat.message
 65
 66    def on_touch_down(self, touch):
 67        # Use client to send requests and do actions
 68        if self.collide_point(*touch.pos):
 69            self.client.send(pgnet.Packet("Click"))
 70```
 71
 72## Running the app
 73We can now call `mousefox.run` to run the app:
 74```python3
 75import mousefox
 76
 77mousefox.run(
 78    game_widget=ClickerWidget,
 79    game_class=ClickerGame,
 80)
 81```
 82
 83Check out the examples
 84[source code](https://github.com/ArielHorwitz/mousefox/tree/master/mousefox/examples/).
 85"""  # noqa: D415
 86
 87
 88import os
 89import sys
 90import asyncio
 91from loguru import logger
 92from . import app
 93from . import examples  # noqa: F401
 94from . import util  # noqa: F401
 95
 96
 97def run(**kwargs):
 98    """Run the app. Takes arguments like `mousefox.AppConfig`.
 99
100    See also: `async_run`.
101    """
102    asyncio.run(async_run(**kwargs))
103
104
105async def async_run(**kwargs):
106    """Coroutine to run the app. Takes arguments like `mousefox.AppConfig`.
107
108    See also: `run`.
109    """
110    logger.info("Starting MouseFox.")
111    config = app.app.AppConfig(**kwargs)
112    mf_app = app.app.App(config)
113    exit_code = await mf_app.async_run()
114    if not config.allow_quit:
115        return
116    # Restart if exit code is -1
117    if exit_code == -1:
118        logger.info("Restarting MouseFox...")
119        os.execl(sys.executable, sys.executable, *sys.argv)
120    logger.info("Closing MouseFox.")
121    quit()
122
123
124AppConfig = app.app.AppConfig