Instances

An instance is essentially a class that defines a single game.
Instanced games are ALWAYS scoped to their very own world when you create one.
New instance = new world.

This is to securely isolate your games from each other, and this is the basic mechanism that makes this whole shebang possible.

An instance will always be a class that extends VitalMinigameInstance.

public class MyInstance extends VitalMinigameInstance {
  
}

Note that we are NOT annotating this class with anything.
This is because an instance class will only be a blueprint for one game "type".
And for that reason we cannot make this class a Spring bean, because if it was, there would only be one single instance of this class. We want to have multiple.

Event handling

Every instance will, by default, always be a listener and can therefore directly receive events.
You can use the default Spigot event handlers in your states.

public class MyInstance extends VitalMinigameInstance {
  @EventHandler
  public void onPlayerJoin(PlayerJoinEvent e) {
    // ...
  }
}

The event handlers that you define in your instances will only receive events if the event that occurred actually came from your instance world.

Game data

To keep all of your game data scoped to only a single instance, you should ALWAYS store it in your instance class.
This way you never risk any game data leaking into other running games on the server.

public class MyInstance extends VitalMinigameInstance {
  private long playerKills = 0;
  private List<UUID> playersAlive = new ArrayList<>();
  
  // ...
}

Starting a game

To start a new game with the instance example shown above, simply use the VitalMinigameInstanceService bean that is globally available and can be injected into any of your other beans (commands, listeners, inventories, etc.).

vitalMinigameInstanceService.registerInstance(
  new MyInstance(),
  (instance) -> {
    // Here we can perform an action that should happen just before the instance was actually registered in Vital (Before any `onRegister` lifecycle for our instance).
  }
);

Stopping a game

To stop a currently running game, simply use the VitalMinigameInstanceService bean that is globally available and can be injected into any of your other beans (commands, listeners, inventories, etc.).

vitalMinigameInstanceService.unregisterInstance(
  myInstance,
  (instance) -> {
    // Here we can perform an action that should happen right before the instance world is deleted.
  },
  (instance) -> {
    // Here we can perform an action that should happen right after the instance world was successfully deleted.
  }
);

Lifecycles