Skip to main content

Set Up Your First Battle

This guide shows you how to configure an encounter zone, trigger a wild battle, and understand the battle flow. By the end, you will have a working battle that you can test in the editor.

The finished result

That is what you are building toward: a wild encounter that fires from a grass tile, with a four-action menu and a rival the encounter table chose.

Prerequisites​

  • MCE is installed and the setup wizard has been completed.
  • You have at least one monster in your database (the demo project's or one you created).
  • You have a scene with a player character and a grid-based tilemap, and a SceneInfo asset for that map.

Step 1: Create an Encounter Zone​

Wild battles are triggered by encounter tiles on your tilemap. An encounter tile is an ordinary tile whose prefab carries the EncounterTile component; the component has a single setting, Encounter Type, that says which kind of encounter the tile starts: Grass, Water, Surfing, Cave, FishingOldRod, FishingGoodRod, FishingSuperRod, Diving, RockSmash, HeadButt, BugContest or Other.

  1. Use an encounter tile prefab -- the engine ships ready-made ones, for example Assets/OpenMon/Game/Prefabs/World/Water/Water/WaterEncounterTile.prefab -- or make your own: create a prefab, add the EncounterTile component and pick its Encounter Type.
  2. Make that prefab the GameObject of a tile asset and paint the tile on the tilemap layer where wild monsters should appear (typically your "Grass" layer).

Each step the player takes onto such a tile rolls against the encounter chance. In a scene whose SceneInfo is marked as a dungeon, every walked tile counts as a Cave encounter without needing painted tiles.

Step 2: Configure the Encounter Table​

What lives in the grass is a WildEncountersSet ScriptableObject, and the map's SceneInfo decides which set answers to which encounter type. Create the set:

  1. Assets > Create > MCE > Battle > Encounters > WildEncountersSet (or the New Wild Encounter Set button in the Hub's Database tab).
  2. Name it something descriptive, like Route1_GrassEncounters.
  3. Fill its three lists:
ListMeaning
Base EncountersMonsters that always show up
Encounters Per MomentExtra monsters for a moment of the day: Night, Dawn, Day or Dusk
Encounters Per WeatherExtra monsters under a given out-of-battle weather

Each entry is a WildEncounter:

FieldDescription
MonsterThe MonsterEntry that can appear
Form CalculatorThe asset that picks the form (SingleFormEncounter always returns one form)
Min Level / Max LevelLevel range of the wild monster (1-100; the max can never go below the min)
WeightRelative chance of this entry (higher = more common)

For example:

MonsterLevel RangeWeight
Flameleon3-540
Leaflet3-540
Sparkit4-620
  1. Open your map's SceneInfo asset and, in its Encounters group, add the entry for the encounter type (for example Grass) and assign your WildEncountersSet. Without that entry the map has no wild monsters for that type.

Step 3: Set Up the Battle Scene​

MCE uses a dedicated battle scene that loads additively over the overworld when a battle starts. You need:

  1. A BattleLauncher asset. It is a ScriptableObject (Create > MCE > Battle > Launcher) bound through the BattleLauncherInstaller, not a component of your scene. Its Battle Scene field points to the battle scene, and it holds the battle music lists. The project's setup already includes one.
  2. The battle scene in your build settings. The default one (Battle.unity, in Assets/OpenMon/Core/Game/Scenes/) is included with MCE.

The BattleLauncher handles the transition:

  • Builds a BattleParameters object (battle type, enemy type, rosters, characters, scenario, weather).
  • Loads the battle scene additively.
  • Hands the parameters to the BattleManager in that scene.
  • Unloads the scene and returns to the overworld when the battle ends.

BattleManager Components​

The BattleManager is the heart of the battle system. In the battle scene, you will find a GameObject with the BattleManager component. It requires fifteen modules next to it, each a MonoBehaviour on the same GameObject, plus the BattleStateMachine:

ModulePurpose
BattleManagerBattlersModuleBattler lookup on both sides, sprites, forms, running away
BattleManagerHealthModuleHP changes, fainting detection and processing
BattleManagerMovesModuleMove execution, accuracy
BattleManagerItemsModuleIn-battle item usage
BattleManagerCaptureModuleWild monster capture mechanics
BattleManagerAIModuleEnemy decision-making
BattleManagerAnimationModuleBattle intro and flow animations
BattleManagerAudioModuleBattle music and sound effects
BattleManagerStatusesModuleStatus conditions (burn, poison, sleep, etc.)
BattleManagerBattlerStatsModuleStat stages and modifications
BattleManagerBattlerSwitchModuleSending battlers in and out
BattleManagerRostersModuleParty management during battle
BattleManagerScenariosModuleWeather, terrain and scenario setup
BattleManagerMegaModuleMega Evolution
BattleManagerCharactersModuleTrainer characters

You do not need to configure these individually. Each module reaches its siblings through the BattleManager, and the rest of the wiring comes from Zenject dependency injection.

Step 4: Know the Battle Loop​

The BattleStateMachine drives the battle as one loop that repeats every turn until the battle is over:

Update fought battlers → Request actions (player menu / AI) →
  → Determine action order → Perform actions →
  → End-of-turn callbacks and status countdown →
  → Check and process fainted battlers → [next turn]
  ... until IsBattleOver → end animation, prize/defeat money, end callbacks

The loop is part of the battle prefab; you do not configure it. To understand or change it, see Battle Internals.

Step 5: Test the Battle​

  1. Make sure your overworld scene has:

    • A PlayerCharacter with a roster containing at least one monster.
    • Encounter tiles painted on a tilemap.
    • A SceneInfo whose Encounters entry for that type points to a configured WildEncountersSet.

  2. Press Play in the editor.

  3. Walk your character onto the encounter tiles.

  4. After a few steps (determined by the encounter chance) a battle will trigger.

Quick Testing

The chance per step comes from the TileEncounterChance table of your MCESettings asset (one value per encounter type), unless the map's SceneInfo defines its own chance for that type. To test battles immediately without walking around, set the chance of the type you are testing to 1 (100%).

Understanding the Battle Flow​

When a battle starts, this is what happens under the hood:

  1. The player steps onto an EncounterTile; the step rolls against the chance for that Encounter Type.
  2. The matching WildEncountersSet of the map gives the possible encounters for the current moment of the day and weather; one is picked by weight and a level is drawn from its range.
  3. A BattleParameters object is created with the wild monster's data and the BattleLauncher loads the battle scene additively.
  4. BattleManager initializes all modules.
  5. The battle introduction plays.
  6. The player is presented with action choices: Fight, Bag, Monster, Run.
  7. Actions execute in priority and speed order.
  8. The loop continues until one side faints or the player runs/captures.
  9. BattleResultParameters are sent back to the overworld (who won, the captured monster, respawn flag).
  10. The battle scene unloads and the overworld resumes.

Battle Types​

Two enums describe what a battle is:

EnumValuesMeaning
BattleTypeSingleBattle, DoubleBattleOne monster per side, or two
EnemyTypeWild, TrainerA wild monster (can be captured) or an NPC trainer (cannot be captured, pays prize money)

Both are carried in BattleParameters and exposed on the BattleManager.

Listening to Battle Events​

Respond to battle events without coupling your gameplay code to internals. The battle launcher is bound in dependency injection, so any script can subscribe to it:

using OpenMon.MCE.Battle;

public class MyBattleTracker : MonoBehaviour
{
    [Inject] private IBattleLauncher battleLauncher;

    private void OnEnable()
    {
        battleLauncher.SubscribeToBattleLaunched(HandleBattleLaunched);
        battleLauncher.SubscribeToBattleEnded(HandleBattleEnded);
    }

    private void OnDisable()
    {
        battleLauncher.UnsubscribeFromBattleLaunched(HandleBattleLaunched);
        battleLauncher.UnsubscribeFromBattleEnded(HandleBattleEnded);
    }

    private void HandleBattleLaunched()
    {
        Debug.Log("A battle has been launched!");
    }

    private void HandleBattleEnded(BattleResultParameters result)
    {
        Debug.Log($"Battle ended. Player won: {result.PlayerWon}");
    }
}

battleLauncher.BattleInProgress tells you whether a battle is running. The SDK also offers IBattleSystem (engine.Battle) with OnBattleStarted and OnBattleEnded, but its engine hooks are not connected yet; see the Public API Guide and IBattleSystem.

Troubleshooting​

IssueSolution
Battle does not triggerCheck that the tile has an EncounterTile with the right Encounter Type, that the map's SceneInfo has a WildEncountersSet for that type, and that TileEncounterChance has a value for it (a missing type counts as 0 and logs a warning once)
Black screen after encounterVerify the battle scene is in your Build Settings scene list and set on the BattleLauncher
Monster appears at level 0Ensure Min Level and Max Level are set in the encounter entry
No battle musicCheck that the BattleLauncher has music in its wild/trainer battle lists and that BattleManagerAudioModule has its audio assigned
Crashes on battle startOpen the OpenMon Hub → Database tab → Validate Database to check for missing database references

Next Steps​