diff --git a/docs/index.rst b/docs/index.rst index 4fdbdac0d5f72ee644505213e45908ff0dd82cc7..6b853ad261320ddb9807f58db7c2ffad461a2840 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,6 +7,7 @@ This is a Python module for implementing bots for Starcraft II. :maxdepth: 2 :caption: Contents: + quickstart unit managers playerconstants diff --git a/docs/quickstart.rst b/docs/quickstart.rst new file mode 100644 index 0000000000000000000000000000000000000000..b708405ca3fb46217665aba8d7ccdf2ec35d09bb --- /dev/null +++ b/docs/quickstart.rst @@ -0,0 +1,115 @@ +.. TODO: How should we host the binaries + +Creating your first bot +======================= + +The goal of this page is to get you quickly started using the API. The +following code block is the bare minimum you need to start Starcraft II and run +your own bot. + +.. code-block:: python + + from library import * + + class DoNothingBot(IDABot): + def __init__(self): + IDABot.__init__(self) + + def on_game_start(self): + IDABot.on_game_start(self) + + def on_step(self): + IDABot.on_step(self) + + + def main(): + coordinator = Coordinator() + bot1 = DoNothingBot() + + participant_1 = create_participants(Race.Terran, bot1) + participant_2 = create_computer(Race.Random, Difficulty.Easy) + + coordinator.set_participants([participant_1, participant_2]) + + coordinator.launch_starcraft() + coordinator.start_game("InterloperTest.SC2Map") + + while coordinator.update(): + pass + + + if __name__ == "__main__": + main() + +Now, let us break it down piece by piece to understand it. + +.. code-block:: python + + from library import * + +.. TODO: Should we really encourage this behaviour? +This imports everything from the library into your namespace. + +Next, we need to define our bot. + +.. code-block:: python + + class DoNothingBot(IDABot): + def __init__(self): + IDABot.__init__(self) + + def on_game_start(self): + IDABot.on_game_start(self) + + def on_step(self): + IDABot.on_step(self) + +A bot which plays Starcraft is defined as a subclass to the class :class:`library.IDABot` which +contains some help code in order to make implementing your bit more straightforward. + +If we look closer at our newly created bot, it has three methods which are all +run at different times. The method ``__init__`` is the constructor, which is +called whenever the bot is first created. + +The method ``on_game_start`` method is run when the game starts. Lastly, the +method ``on_step`` is run on every time step of the game and thus where most of +the decision making is going to be implemented. + +Moving on, we have the code which sets up a game of Starcraft II: + +.. code-block:: python + + def main(): + coordinator = Coordinator() + bot1 = DoNothingBot() + + participant_1 = create_participants(Race.Terran, bot1) + participant_2 = create_computer(Race.Random, Difficulty.Easy) + + coordinator.set_participants([participant_1, participant_2]) + + coordinator.launch_starcraft() + coordinator.start_game("InterloperTest.SC2Map") + + while coordinator.update(): + pass + + + if __name__ == "__main__": + main() + +This is where the constructor of the bot is called. If we want to play to bots +against each other we could change the row: + +.. code-block:: python + + participant_2 = create_computer(Race.Random, Difficulty.Easy) + +to: + +.. code-block:: python + + bot2 = SomeOtherBot() + participant_2 = create_participant(Race.Terran, bot2) + +where ``SomeOtherBot`` is a bot defined in the same way as ``DoNothingBot``.