MonsterInstance

The runtime data container for a single monster — species, form, stats, moves, ability, held item, friendship and more. This is the object you get back when you index a Roster (e.g. player.PlayerRoster[0]), so it is the type your game code manipulates most.

The species is shared by every copy; the instance is why no two are the same.

Namespace: OpenMon.MCE.Monster

Concrete data type, not an SDK interface

Unlike the OpenMon.MCE.SDK interfaces, MonsterInstance is a concrete serializable class. The members below are the main surface most buyers use; the full class has additional members (breeding, evolution, encounter and sprite helpers). See the source code (Source tier) for the complete API.

Definition

[Serializable]
public class MonsterInstance : Loggable<MonsterInstance>, IWorldDataContainer, ICommandParameter
{
    public MonsterEntry Species;
    public Form Form;
    public bool IsNullEntry { get; }
    public DataByFormEntry FormData { get; }

    public MonsterStatData StatData;
    public MonsterPhysicalData PhysicalData;
    public OriginData OriginData;

    public bool HasNickname;
    public string Nickname;
    public string CurrentTrainer;
    public byte Friendship;
    public uint CurrentHP;

    public MoveSlot[] CurrentMoves;
    public List<Move> LearntMoves;
    public Item HeldItem;

    public bool CanBattle { get; }
    public float Height { get; }
    public float Weight { get; }

    public MonsterInstance(MCESettings settings, MonsterDatabaseInstance database,
        MonsterEntry species, Form form, byte level, /* ...many optional overrides... */);

    public string GetNameOrNickName(ILocalizer localizer);
    public (int NewHP, int PreviousHP, bool TriggeredForceSurvive) ChangeHP(int amount, bool forceSurvive = false);
    public void CompletelyHeal();
    public bool IsAtMaxHP();
    public void RaiseExperience(ExperienceLookupTable lookupTable, uint amount, Action<LevelUpData> levelUpCallback);
    public int GetExperienceForNextLevel(ExperienceLookupTable lookupTable);
    public void ChangeFriendship(int amount, SceneInfoAsset currentScene, ILocalizer localizer);
    public Dictionary<Stat, uint> GetStats(BattleManager battleManager);
    public (MonsterType, MonsterType) GetTypes(MCESettings settings, BattleManager battleManager);
    public Ability GetAbility();
    public void SetAbility(Ability ability);
    public bool KnowsMove(Move move);
    public bool CanLearnMove(Move move);
    public List<MoveSlot> GetMovesWithPP();
    public MonsterInstance Clone();
}

Fields & Properties

Species

Species of this monster.

Type: MonsterEntry

Form

Form of this monster (regional variant, gender form, shiny, etc.).

Type: Form

IsNullEntry

Is this entry null? Useful because Unity creates an instance with everything set to null when serializing empty roster slots.

Type: bool (read-only) — true when Species == null || Form == null.

FormData

Get the form data of this monster species (the per-form record holding base stats, types, learnset, etc.).

Type: DataByFormEntry (read-only) — equivalent to Species[Form].

StatData

Stat data for this monster. This is where the monster's level lives (StatData.Level, a byte), along with its Nature and CurrentLevelExperience.

Type: MonsterStatData

PhysicalData

Physical data for this monster (gender, height/weight modifiers). Read gender via PhysicalData.Gender.

Type: MonsterPhysicalData

OriginData

Origin data of this monster (region, location, capture ball, original trainer, whether it is an alpha).

Type: OriginData

HasNickname / Nickname

Whether the monster has a nickname, and the nickname itself when it does.

Type: bool / string

CurrentTrainer

Current trainer of this monster.

Type: string

Friendship

This monster's friendship value.

Type: byte (0–255)

CurrentHP

This monster's current HP.

Type: uint

CurrentMoves

The monster's move slots. A monster has 4 slots; each MoveSlot carries the Move and its current PP.

Type: MoveSlot[]

LearntMoves

Moves this monster has learnt in its life.

Type: List<Move>

HeldItem

This monster's held item.

Type: Item

CanBattle

Can this monster battle? true when CurrentHP > 0 and the monster is not an egg.

Type: bool (read-only)

Height

Get the height of the monster (form height × physical height modifier).

Type: float (read-only)

Weight

Get the weight of the monster (form weight × physical modifier, then adjusted by the ability's weight modifiers).

Type: float (read-only)

Methods

MonsterInstance(...) constructor

Constructor for a monster instance with overrides for most of its data. Only settings, database, species, form and level are required — the rest have sensible defaults (random nature/ability, no nickname, OriginData.Type.Caught, etc.).

Parameter	Type	Description
settings	MCESettings	Internal settings for MCE reference
database	MonsterDatabaseInstance	Database used to create this monster
species	MonsterEntry	Species of this monster
form	Form	Form of this monster (invalid form falls back to the default)
level	byte	Level of this monster
(many optional)		nature, ability, gender, IVs/EVs, moves, nickname, trainer, ball, ribbons, held item, isEgg, and more

Prefer Roster.AddMonster

In normal gameplay you usually create monsters through Roster.AddMonster(...), which forwards to this constructor and slots the monster into the party for you.

GetNameOrNickName(ILocalizer localizer)

Retrieve the name or nickname of this monster.

Parameter	Type	Description
localizer	ILocalizer	Reference to the localizer

Returns: string — the localized nickname if it has one, the localized species name otherwise (or the "Egg" string when it is an egg).

ChangeHP(int amount, bool forceSurvive = false)

Change the HP of this monster by an unclamped amount (clamped internally to [0..maxHP], or [1..maxHP] when forceSurvive is set).

Parameter	Type	Description
amount	int	The unclamped amount to change the HP by
forceSurvive	bool	Force the monster to survive the hit?

Returns: (int NewHP, int PreviousHP, bool TriggeredForceSurvive).

CompletelyHeal()

Completely heal this monster — restores HP to max, refills every move slot's PP, and clears its status.

IsAtMaxHP()

Check if the monster is at max health.

Returns: bool — true if it is.

RaiseExperience(ExperienceLookupTable lookupTable, uint amount, Action<LevelUpData> levelUpCallback)

Raise the experience of this monster, handling level-ups (and their move-learn events) along the way.

Parameter	Type	Description
lookupTable	ExperienceLookupTable	Experience lookup table to use
amount	uint	Amount of experience to raise
levelUpCallback	Action<LevelUpData>	Callback raised each time the monster levels up

GetExperienceForNextLevel(ExperienceLookupTable lookupTable)

Get the experience needed for the next level.

Returns: int — the experience required for the next level.

ChangeFriendship(int amount, SceneInfoAsset currentScene, ILocalizer localizer)

Change the friendship of this monster (applies location and capture-ball modifiers before clamping to [0..255]).

Parameter	Type	Description
amount	int	Amount to change
currentScene	SceneInfoAsset	Current scene we are in
localizer	ILocalizer	Reference to the localizer

GetStats(BattleManager battleManager)

Retrieve the current stats of this monster.

Parameter	Type	Description
battleManager	BattleManager	Reference to the battle manager if in battle; pass null outside of battle

Returns: Dictionary<Stat, uint> — each stat mapped to its computed value.

GetTypes(MCESettings settings, BattleManager battleManager)

Retrieve the types of this monster. They can be modified by volatile battle states.

Returns: (MonsterType, MonsterType) — the two types (the second may be null for single-typed monsters).

GetAbility()

Get this monster's ability.

Returns: Ability.

SetAbility(Ability ability)

Set the new ability of this monster.

Parameter	Type	Description
ability	Ability	New ability

KnowsMove(Move move)

Check if the monster knows a move.

Returns: bool — true if it does.

CanLearnMove(Move move)

Check if the monster can learn a move (i.e. the move is in its learnset and it does not already know it).

Returns: bool — true if it can.

GetMovesWithPP()

Retrieve a list of the moves that still have PP.

Returns: List<MoveSlot>.

Clone()

Clone this instance. Returns null for a null entry; deep-clones stat data and copies the rest.

Returns: MonsterInstance.

Usage Example

using OpenMon.MCE.SDK;
using OpenMon.MCE.Monster;
using Zenject;

public class LeadMonsterInspector : MonoBehaviour
{
    [Inject] private IMonsterCaptureEngine engine;

    private void Start()
    {
        Roster roster = engine.Player.PlayerRoster;
        if (roster.RosterSize == 0) return;

        MonsterInstance lead = roster[0];

        Debug.Log($"Species : {lead.Species.name}");
        Debug.Log($"Level   : {lead.StatData.Level}");
        Debug.Log($"HP      : {lead.CurrentHP}");
        Debug.Log($"Friend. : {lead.Friendship}");
        Debug.Log($"Can battle: {lead.CanBattle}");

        // Inspect the moveset.
        foreach (MoveSlot slot in lead.GetMovesWithPP())
            Debug.Log($"Move: {slot.Move.name} ({slot.CurrentPP} PP)");

        // Full restore.
        lead.CompletelyHeal();
    }
}