Menu

Objects & Natives API

Moonwell.Objects base classes and helpers

Every generated standard object class in Moonwell.Objects inherits from one of eight kind base classes:

Base classRuntime baseUsed for
StandardUnitMoonwell.UnitStandard and custom non-hero units
StandardHeroMoonwell.Hero (: Unit)Standard and custom heroes
StandardItemMoonwell.ItemStandard and custom items
StandardDestructableMoonwell.DestructableStandard and custom destructables
StandardDoodadMoonwell.DoodadStandard and custom doodads
StandardAbilityMoonwell.AbilityStandard and custom abilities
StandardBuffMoonwell.BuffStandard and custom buffs with in-game status icons
StandardUpgradeMoonwell.UpgradeStandard and custom upgrades

Each kind base class provides four protected helper methods for use inside object constructors:

MethodDescription
protected static Levels<T> Levels<T>(params T[] values)Creates a Levels<T> from explicit level values (level 1, level 2, ...).
protected static Levels<T> PerLevel<T>(Func<int, T> formula)Creates a lazy Levels<T> evaluated for each 1-based level (1..LevelCount).
protected void Set(string field, object value)Sets a single-value object field by its raw 4-character field id (for example, Set("uhpm", 800)).
protected void Set(string field, int level, object value)Sets a leveled object field at 1-based level by its raw 4-character field id (for example, Set("Htb1", 2, 250f)).

Wrapper types and attributes

Levels<T>

public sealed class Levels<T>

Represents a per-level field on an ability, upgrade, or doodad.

MemberLocal-safeDescription
public int Count { get; }YesNumber of explicit values passed to Levels(...) (0 when created via PerLevel).
public T this[int level] { get; }YesReturns the value at 1-based level (level >= 1).

ObjectList<T>

public sealed class ObjectList<T>

Represents a comma-separated list of object ids (such as Abilities, HeroAbilities, Requires, Trains, Builds, Sells, SellsUnits, or Buffs).

MemberLocal-safeDescription
public int Count { get; }YesNumber of object ids currently in the list.
public bool Contains<TObject>() where TObject : TYesReturns true if TObject is in the list.
public void Add<TObject>() where TObject : TNoAppends TObject to the list if not already present (constructor-only).
public void Remove<TObject>() where TObject : TNoRemoves TObject from the list if present (constructor-only).

ObjectRef<T>

public sealed class ObjectRef<T>

Represents a single typed object reference field.

MemberLocal-safeDescription
public bool Is<TObject>() where TObject : TYesReturns true if this reference currently points to TObject.
public void Set<TObject>() where TObject : TNoPoints this reference at TObject (constructor-only).

[ObjectId] and [Replaces]

AttributeTargetDescription
[ObjectId(string id)]classPins the 4-character object id (such as [ObjectId("H001")]) for a declared custom object class.
[Replaces]classWrites the declared class's modified fields directly onto its standard base class's own id and registers the declared class for that standard id at run time.

Standard object namespaces and naming

Namespaces by kind

Object kindNamespaces
Units & HeroesMoonwell.Objects.Units.Human, .Orc, .Undead, .NightElf, .Naga, .Demon, .Creeps, .Critters, .Campaign, .Other
AbilitiesMoonwell.Objects.Abilities.Human, .Orc, .Undead, .NightElf, .Naga, .Creeps, .Other
BuffsMoonwell.Objects.Buffs.Human, .Orc, .Undead, .NightElf, .Other
UpgradesMoonwell.Objects.Upgrades.Human, .Orc, .Undead, .NightElf, .Naga, .Demon, .Other
ItemsMoonwell.Objects.Items
DestructablesMoonwell.Objects.Destructables
DoodadsMoonwell.Objects.Doodads

Class naming rules

  1. Each standard object class is named in PascalCase after its English in-game name (Footman, Archmage, StormBolt, ClawsOfAttack15, SummerTreeWall).
  2. When a campaign or special hero has a single Propernames entry (Hjai → "Jaina"), that proper name is used as the class name (Jaina). When several campaign heroes share a proper name, all of them keep their id (ArthasHart, ArthasUear).
  3. Among objects in one namespace that share a name, each gets its id appended, except the one with the first id when it isn't a campaign object (for example, WaterElemental for hwat, WaterElementalHwt2 for hwt2, and WaterElementalHwt3 for hwt3). A name that is a C# keyword, the namespace's last part, or a reserved type name also gets its id appended.

Hand-picked property names (98 fields)

Every standard object class exposes all of its World Editor fields as typed properties. The 98 most common fields across the seven kinds have short hand-picked names; all remaining fields are named in PascalCase after their World Editor display labels.

Units and heroes (unit — 41 fields)

PropertyField idType
Nameunamstring
HitPointsuhpmint
HitPointRegenuhprfloat
Manaumpmint
ManaRegenumprfloat
Armorudefint
Speedumvsint
SightRangeusidint
CollisionSizeucolfloat
GoldCostugolint
LumberCostulumint
Foodufooint
FoodProducedufmaint
BuildTimeubldint
Levelulevint
AbilitiesuabiObjectList<Ability>
HeroAbilitiesuhabObjectList<Ability>
RequiresureqObjectList<object>
Modelumdlstring
Scaleuscafloat
Iconuicostring
Tooltiputipstring
ExtendedTooltiputubstring
Hotkeyuhotstring
AttackTypeua1tstring
Damageua1bint
DamageDiceua1dint
DamageSidesua1sint
AttackCooldownua1cfloat
AttackRangeua1rint
Strengthustrint
Agilityuagiint
Intelligenceuintint
StrengthPerLevelustpfloat
AgilityPerLeveluagpfloat
IntelligencePerLeveluinpfloat
PrimaryAttributeuprastring
TrainsutraObjectList<Unit>
BuildsubuiObjectList<Unit>
SellsuseiObjectList<Item>
SellsUnitsuseuObjectList<Unit>

Items (item — 15 fields)

PropertyField idType
Nameunamstring
HitPointsihtpint
GoldCostigolint
LumberCostilumint
Levelilevint
AbilitiesiabiObjectList<Ability>
Modelifilstring
Scaleiscafloat
Iconiicostring
Tooltiputipstring
ExtendedTooltiputubstring
Descriptionidesstring
Hotkeyuhotstring
RequiresureqObjectList<object>
Chargesiuseint

Abilities (ability — 21 fields)

Plus per-ability data fields (such as Damage on StormBolt), which are named after the ability's own MetaData labels.

PropertyField idType
Nameanamstring
LevelCountalevint
CooldownacdnLevels<float>
ManaCostamcsLevels<int>
RangearanLevels<float>
AreaaareLevels<float>
DurationadurLevels<float>
HeroDurationahduLevels<float>
CastTimeacasLevels<float>
BuffsabufObjectList<Buff>
TargetsatarLevels<string>
Iconaartstring
Tooltipatp1Levels<string>
ExtendedTooltipaub1Levels<string>
LearnTooltiparetstring
LearnExtendedTooltiparutstring
Hotkeyahkystring
LearnHotkeyarhkstring
RequiresareqObjectList<object>
Orderaordstring
RequiredLevelarlvint

Buffs (buff — 4 fields)

PropertyField idType
Namefnamstring
Tooltipftipstring
ExtendedTooltipfubestring
Iconfartstring

Upgrades (upgrade — 7 fields)

PropertyField idType
NamegnamLevels<string>
Tooltipgtp1Levels<string>
ExtendedTooltipgub1Levels<string>
Hotkeyghk1Levels<string>
Icongar1Levels<string>
LevelCountglvlint
RequiresgreqObjectList<object>

Destructables (destructable — 7 fields)

PropertyField idType
Namebnamstring
HitPointsbhpsfloat
Modelbfilstring
BuildTimebbutint
RepairTimebretint
RepairGoldCostbregint
RepairLumberCostbrelint

Doodads (doodad — 3 fields)

PropertyField idType
Namednamstring
Modeldfilstring
Scaleddesfloat

Moonwell.Natives

Moonwell.Natives (Moonwell.Natives.dll) provides direct C# bindings for Warcraft III's common.j and Blizzard.j in the Moonwell namespace. Import Moonwell and call functions and constants through Natives:

using Moonwell;

// ...
Natives.CreateUnit(player.Handle, id, x, y, facing);

[!WARNING] Do not use using static Moonwell.Natives;. Using a handle constant (such as ATTACK_TYPE_MAGIC, DAMAGE_TYPE_MAGIC, DAMAGE_TYPE_FIRE, or WEAPON_TYPE_WHOKNOWS) through a using static import crashes moonwell build 0.1.2 with NullReferenceException, and the static import also makes Player.Get(0) fail with CS0119 because Natives.Player(int) shadows Moonwell.Player.

Natives static class

public static class Natives (in the Moonwell namespace) contains:

  • All 2,796 functions from common.j and Blizzard.j (Warcraft III 3.0.1.24370) with their exact JASS names (CreateUnit, GetTriggerUnit, UnitDamageTarget, AddSpecialEffect, SetUnitPosition, BlzGetUnitMaxHp, etc.).
  • All common.j and Blizzard.j constants (PLAYER_NEUTRAL_AGGRESSIVE, ATTACK_TYPE_HERO, DAMAGE_TYPE_NORMAL, EVENT_PLAYER_UNIT_DEATH, bj_RADTODEG, etc.).
  • All bj_* global variables exposed as static properties (bj_lastCreatedUnit, bj_mapInitialPlayableArea, etc.).
  • Sync attributes ([CreatesHandle], [ChangesState], [MachineLocal], [Desyncs]) on the natives and Blizzard.j functions that create handles, change game state, read machine-local state, or desync (untagged natives also exist).

Handle types (namespace Moonwell)

All JASS handle types are generated in namespace Moonwell (in Moonwell.Natives.dll) with their lowercase JASS names and inheritance hierarchy:

  • handle — root handle type.
    • agent : handle — reference-counted handle types (player, widget, unit, item, destructable, timer, trigger, group, force, rect, region, location, effect, sound, dialog, button, quest, timerdialog, leaderboard, multiboard, multiboarditem, hashtable, framehandle, boolexpr, conditionfunc : boolexpr, filterfunc : boolexpr, fogmodifier, etc.).
    • Non-agent handles (: handle) — enum-like and lightweight handles (alliancetype, attacktype, damagetype, weapontype, armortype, race, playercolor, playerslotstate, unitevent, playerunitevent, widgetevent, limitop, texttag, lightning, image, ubersplat, originframetype, framepointtype, textaligntype, oskeytype, etc.).

Not affiliated with Blizzard Entertainment