"""
First advantage of using stages:
There're 3 methods that handle the flow of the stages.
set_stage_group - erases current stage queue and starts a new stage group;
insert_stage_group - inserts a stage group to the begginning of the queue;
append_stage_group - appends;

You can't achieve this behaviour with methods.
I mean, you can achieve insert_stage_group by calling some method directly
- that way it is executed before others.

If you do
"""

def game_start(self):
    self.spawn_players()
    self.setup_damage_hooks()


"""
And spawn_players suddenly decides that it ran out of spawnpoints, with stages I would just do
"""

set_stage_group('destroy')      # Erases the queue, so setup_damage_hooks won't get executed


"""
with methods you can't cancel those that will be executed later


Second advantage of using stages:
You can undo them. There's a method .undo_stages that undoes all stages that have been executed
Why would I need it? Imagine you have an 'destroy' method/stage. It should stop the game from any
stage it is currently at.

"""

def game_start(self):
    self.spawn_players()
    self.setup_damage_hooks()
    self.register_event_handlers()

""" Now, with methods you would probably do this """

def destroy(self):
    self.undo_spawn_players()   # Teleports players back to their positions
    self.undo_setup_damage_hooks()    # Obviously removes the hooks
    self.undo_register_event_handlers()     # Unregisters event handlers

"""
Works fine when the game is started. Players are teleported from game area,
damage hooks are unset, event handlers are unregistered.

But what if .spawn_players decides to destroy the game? You only need to teleport the players back,
but trying to remove the hooks and unregister event handlers will raise an exception -
because those have not been registered yet.

Then you need to keep a track of methods that have been executed:
"""

def destroy(self):
    if self._players_were_spawned:
        self.undo_spawn_players()

    if self._hooks_were_set_up:
        self.undo_setup_damage_hooks()

    if self._handlers_were_registered:
        self.undo_register_event_handlers()

"""
or implement different 'destroy' methods:
"""

def destroy_all(self): ...
def destroy_all_but_hooks_and_handlers(self): ...
def destroy_all_but_handlers(self): ...

"""
But what if something external tries to destroy the game? It will need to know what method to call.


With stages I just do
"""

@stage('survival-equip-damage-hooks')
def stage_survival_equip_damage_hooks(self):
    # ...

@stage('undo-survival-equip-damage-hooks')
def stage_undo_survival_equip_damage_hooks(self):
    # ...

"""
Any 'undo-X' stage will be called when the game is being destroyed and stage 'X' has already been executed.

.undo_stages also receives optional argument of names of exact stage groups that need to be cancelled
- so the game is not aborted completely.

For example, I have a group of stages that defines preparation of the game (countdown, players freezing)
and to end this preparation I just call .undo_stages - countdown stops, players are unfrozen.
And so it will be stopped successfully even if the game is being destroyed during its preparation
- countdown stops (if it has been started), players are unfrozen (if they were frozen).