Difference between revisions of "Script/LevelReference"

From SF3
Jump to: navigation, search
(→‎class LevelReference)
(→‎Arena Game Mode)
 
(32 intermediate revisions by 2 users not shown)
Line 213: Line 213:
 
|-
 
|-
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]  
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]  
−
| style='color: black; width: 90%; line-height: 1.0;' | '''RegisterCreatureEventByDescription''' (const [[../LogicEnums#ECreatureEvent|ECreatureEvent]] ''_EventType'', [[../LogicCallbacks|TOnCreatureEvent@]] ''_pFunction'', const [[../BasicDataTypes|string]]&in ''_sDescriptionName'', const [[../BasicDataTypes|uint8]] ''_Faction'')
+
| style='color: black; width: 90%; line-height: 1.0;' | '''RegisterCreatureEventByDescription''' (const [[../LogicEnums#ECreatureEvent|ECreatureEvent]] ''_EventType'', [[../LogicCallbacks|TOnCreatureEvent@]] ''_pFunction'', const [[../BasicDataTypes|string]]&in ''_sDescriptionName'', const [[../BasicDataTypes|uint8]] ''_Faction'', const [[../BasicDataTypes|string]]&in ''_sParam'' = "")
 
|-
 
|-
 
|
 
|
Line 242: Line 242:
 
|
 
|
 
| style = 'color: #505050; line-height: 0.5;' |''register building event by individual building name (i.e. name of the building in the level editor)''
 
| style = 'color: #505050; line-height: 0.5;' |''register building event by individual building name (i.e. name of the building in the level editor)''
 +
|-
 +
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]
 +
| style='color: black; width: 90%; line-height: 1.0;' | '''RegisterBuildingEventByIndividual''' (const [[../LogicEnums#EBuildingEvent|EBuildingEvent]] ''_EventType'', [[../LogicCallbacks|TOnBuildingEvent@]] ''_pFunction'', const [[../Building|Building]]&in ''_Building'')
 +
|-
 +
|
 +
| style = 'color: #505050; line-height: 0.5;' |''register building event by individual building instance''
 +
|-
 +
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]
 +
| style='color: black; width: 90%; line-height: 1.0;' | '''RegisterBuildingEventByDescription''' (const [[../LogicEnums#EBuildingEvent|EBuildingEvent]] ''_EventType'', [[../LogicCallbacks|TOnBuildingExtendedEvent@]] ''_pFunction'', const [[../BasicDataTypes|string]]&in ''_sDescriptionName'', const [[../BasicDataTypes|uint8]] ''_Faction'')
 +
|-
 +
|
 +
| style = 'color: #505050; line-height: 0.5;' |''same as above, but receives extra information for certain event types''
 +
|-
 +
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]
 +
| style='color: black; width: 90%; line-height: 1.0;' | '''RegisterBuildingEventByIndividual''' (const [[../LogicEnums#EBuildingEvent|EBuildingEvent]] ''_EventType'', [[../LogicCallbacks|TOnBuildingExtendedEvent@]] ''_pFunction'', const [[../BasicDataTypes|string]]&in ''_sBuildingName'')
 +
|-
 +
|
 +
| style = 'color: #505050; line-height: 0.5;' |''same as above, but receives extra information for certain event types''
 +
|-
 +
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]
 +
| style='color: black; width: 90%; line-height: 1.0;' | '''RegisterBuildingEventByIndividual''' (const [[../LogicEnums#EBuildingEvent|EBuildingEvent]] ''_EventType'', [[../LogicCallbacks|TOnBuildingExtendedEvent@]] ''_pFunction'', const [[../Building|Building]]&in ''_Building'')
 +
|-
 +
|
 +
| style = 'color: #505050; line-height: 0.5;' |''same as above, but receives extra information for certain event types''
 
|-
 
|-
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]  
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]  
Line 254: Line 278:
 
|
 
|
 
| style = 'color: #505050; line-height: 0.5;' |''register building event involving creatures by individual building name (i.e. name of the building in the level editor)''
 
| style = 'color: #505050; line-height: 0.5;' |''register building event involving creatures by individual building name (i.e. name of the building in the level editor)''
 +
|-
 +
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]
 +
| style='color: black; width: 90%; line-height: 1.0;' | '''RegisterBuildingCreatureEventByIndividual''' (const [[../LogicEnums#EBuildingCreatureEvent|EBuildingCreatureEvent]] ''_EventType'', [[../LogicCallbacks|TOnBuildingCreatureEvent@]] ''_pFunction'', const [[../Building|Building]]&in ''_Building'')
 +
|-
 +
|
 +
| style = 'color: #505050; line-height: 0.5;' |''register building event involving creatures by individual building instance''
 
|-
 
|-
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]  
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]  
Line 288: Line 318:
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]  
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]  
 
| style='color: black; width: 90%; line-height: 1.0;' | '''SetTimer''' ([[../LogicCallbacks#TOnTimerEvent|TOnTimerEvent@]] ''_pFunction'', const [[../BasicDataTypes|uint]] ''_uInterval'')
 
| style='color: black; width: 90%; line-height: 1.0;' | '''SetTimer''' ([[../LogicCallbacks#TOnTimerEvent|TOnTimerEvent@]] ''_pFunction'', const [[../BasicDataTypes|uint]] ''_uInterval'')
 +
|-
 +
|
 +
| style = 'color: #505050; line-height: 0.5;' |''register a timer event to be called after _uInterval seconds.''
 +
|-
 +
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]
 +
| style='color: black; width: 90%; line-height: 1.0;' | '''SetTimer''' ([[../LogicCallbacks#TOnTimerUserDataEvent|TOnTimerUserDataEvent@]] ''_pFunction'', const [[../BasicDataTypes|uint]] ''_uInterval'', const [[../BasicDataTypes|string]]&in ''_sUserData'')
 
|-
 
|-
 
|
 
|
Line 294: Line 330:
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]  
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]  
 
| style='color: black; width: 90%; line-height: 1.0;' | '''SetTimerMS''' ([[../LogicCallbacks#TOnTimerEvent|TOnTimerEvent@]] ''_pFunction'', const [[../BasicDataTypes|uint]] ''_uIntervalMS'')
 
| style='color: black; width: 90%; line-height: 1.0;' | '''SetTimerMS''' ([[../LogicCallbacks#TOnTimerEvent|TOnTimerEvent@]] ''_pFunction'', const [[../BasicDataTypes|uint]] ''_uIntervalMS'')
 +
|-
 +
|
 +
| style = 'color: #505050; line-height: 0.5;' |''register a timer event to be called after _uInterval MILLIseconds.
 +
 +
NOTE: this timer is not 100% precise, it may be off by up to +/- 50 ms.''
 +
|-
 +
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]
 +
| style='color: black; width: 90%; line-height: 1.0;' | '''SetTimerMS''' ([[../LogicCallbacks#TOnTimerUserDataEvent|TOnTimerUserDataEvent@]] ''_pFunction'', const [[../BasicDataTypes|uint]] ''_uIntervalMS'', const [[../BasicDataTypes|string]]&in ''_sUserData'')
 
|-
 
|-
 
|
 
|
Line 302: Line 346:
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]  
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]  
 
| style='color: black; width: 90%; line-height: 1.0;' | '''CancelTimer''' ([[../LogicCallbacks#TOnTimerEvent|TOnTimerEvent@]] ''_pFunction'')
 
| style='color: black; width: 90%; line-height: 1.0;' | '''CancelTimer''' ([[../LogicCallbacks#TOnTimerEvent|TOnTimerEvent@]] ''_pFunction'')
 +
|-
 +
|
 +
| style = 'color: #505050; line-height: 0.5;' |''cancel all currently registered timer events calling the given script function (does NOT include timers created using CreateCountdownTimer or CreateStopwatchTimer!)''
 +
|-
 +
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]
 +
| style='color: black; width: 90%; line-height: 1.0;' | '''CancelTimer''' ([[../LogicCallbacks#TOnTimerUserDataEvent|TOnTimerUserDataEvent@]] ''_pFunction'', const [[../BasicDataTypes|string]]&in ''_sUserData'')
 
|-
 
|-
 
|
 
|
Line 310: Line 360:
 
Functions for controlling win/lose conditions.
 
Functions for controlling win/lose conditions.
 
{| border='0' style ='border:solid 1px #eeeedd; color: black; width: 1200px;background-color: #ffffcc;' cellspacing='0' cellpadding='7'
 
{| border='0' style ='border:solid 1px #eeeedd; color: black; width: 1200px;background-color: #ffffcc;' cellspacing='0' cellpadding='7'
 +
|-
 +
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|bool]]
 +
| style='color: black; width: 90%; line-height: 1.0;' | '''HasWonGame''' (const [[../BasicDataTypes|uint8]] ''_Faction'') const
 +
|-
 +
|
 +
| style = 'color: #505050; line-height: 0.5;' |''has the given faction won the game?''
 +
|-
 +
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|bool]]
 +
| style='color: black; width: 90%; line-height: 1.0;' | '''HasLostGame''' (const [[../BasicDataTypes|uint8]] ''_Faction'') const
 +
|-
 +
|
 +
| style = 'color: #505050; line-height: 0.5;' |''has the given faction lost the game?''
 
|-
 
|-
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]  
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]  
Line 322: Line 384:
 
|
 
|
 
| style = 'color: #505050; line-height: 0.5;' |''show the defeat screen to the given faction''
 
| style = 'color: #505050; line-height: 0.5;' |''show the defeat screen to the given faction''
 +
|-
 +
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]
 +
| style='color: black; width: 90%; line-height: 1.0;' | '''ResetSuccessState''' (const [[../BasicDataTypes|uint8]] ''_Faction'')
 +
|-
 +
|
 +
| style = 'color: #505050; line-height: 0.5;' |''reset success state (needed to fix faulty savegames)''
 
|}
 
|}
  
Line 345: Line 413:
 
|
 
|
 
| style = 'color: #505050; line-height: 0.5;' |''get the race of the given faction''
 
| style = 'color: #505050; line-height: 0.5;' |''get the race of the given faction''
 +
|-
 +
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]
 +
| style='color: black; width: 90%; line-height: 1.0;' | '''SetFactionRace''' (const [[../BasicDataTypes|uint8]] ''_Faction'', const [[../BasicDataTypes|ERace]] ''_Race'')
 +
|-
 +
|
 +
| style = 'color: #505050; line-height: 1.0;' |''set the race of the given faction. WARNING: DO NOT set the race to any race not yet present in the level. Otherwise you may cause considerable loading stutters when the faction produces buildings or units.''
 
|-
 
|-
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|uint8]]  
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|uint8]]  
Line 357: Line 431:
 
|
 
|
 
| style = 'color: #505050; line-height: 0.5;' |''set the color index to be used by the given faciton''
 
| style = 'color: #505050; line-height: 0.5;' |''set the color index to be used by the given faciton''
 +
|-
 +
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|bool]]
 +
| style='color: black; width: 90%; line-height: 1.0;' | '''CanFactionUseGodstones''' (const [[../BasicDataTypes|uint8]] ''_Faction'') const
 +
|-
 +
|
 +
| style = 'color: #505050; line-height: 0.5;' |''check whether the given faction can use godstones''
 +
|-
 +
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]
 +
| style='color: black; width: 90%; line-height: 1.0;' | '''AllowGodstoneUse''' (const [[../BasicDataTypes|uint8]] ''_Faction'', const [[../BasicDataTypes|bool]] ''_bAllow'')
 +
|-
 +
|
 +
| style = 'color: #505050; line-height: 0.5;' |''allow a faction to use godstones (or don't)''
 
|-
 
|-
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]  
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]  
Line 438: Line 524:
 
|
 
|
 
| style = 'color: #505050; line-height: 0.5;' |''end an ongoing notification at the given location for the given faction.''
 
| style = 'color: #505050; line-height: 0.5;' |''end an ongoing notification at the given location for the given faction.''
 +
|-
 +
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]
 +
| style='color: black; width: 90%; line-height: 1.0;' | '''ShowQuestNotification''' (const [[../BasicDataTypes|uint8]] ''_Faction'', const [[../BasicDataTypes|string]]&in ''_sNotificationName'', const [[../BasicDataTypes|string]]&in ''_sQuestName'', const [[../BasicDataTypes|string]]&in ''_sTaskName'')
 +
|-
 +
|
 +
| style = 'color: #505050; line-height: 0.5;' |''show quest-related notification''
 
|-
 
|-
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]  
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]  
Line 451: Line 543:
 
|-
 
|-
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|uint]]  
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|uint]]  
−
| style='color: black; width: 90%; line-height: 1.0;' | '''CreateCountdownTimer''' (const [[../BasicDataTypes|uint]] ''_uDisplayTextId'', const [[../BasicDataTypes|uint]] ''_uSeconds'', [[../LogicCallbacks|TOnTimerEvent@]] ''_pFunction'' = null, const [[../BasicDataTypes|uint8]] ''_uFaction'' = kMaxFactions)
+
| style='color: black; width: 90%; line-height: 1.0;' | '''CreateCountdownTimer''' (const [[../BasicDataTypes|uint]] ''_uDisplayTextId'', const [[../BasicDataTypes|uint]] ''_uSeconds'', [[../LogicCallbacks|TOnTimerEvent@]] ''_pFunction'' = null, const [[../BasicDataTypes|uint8]] ''_uFaction'' = kMaxFactions, const [[../BasicDataTypes|string]]&in ''_sName'' = "")
 
|-
 
|-
 
|
 
|
Line 460: Line 552:
 
|-
 
|-
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|uint]]  
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|uint]]  
−
| style='color: black; width: 90%; line-height: 1.0;' | '''CreateCountdownTimerMS''' (const [[../BasicDataTypes|uint]] ''_uDisplayTextId'', const [[../BasicDataTypes|uint]] ''_uMilliSeconds'', [[../LogicCallbacks|TOnTimerEvent@]] ''_pFunction'' = null, const [[../BasicDataTypes|uint8]] ''_uFaction'' = kMaxFactions)
+
| style='color: black; width: 90%; line-height: 1.0;' | '''CreateCountdownTimerMS''' (const [[../BasicDataTypes|uint]] ''_uDisplayTextId'', const [[../BasicDataTypes|uint]] ''_uMilliSeconds'', [[../LogicCallbacks|TOnTimerEvent@]] ''_pFunction'' = null, const [[../BasicDataTypes|uint8]] ''_uFaction'' = kMaxFactions, const [[../BasicDataTypes|string]]&in ''_sName'' = "")
 
|-
 
|-
 
|
 
|
Line 468: Line 560:
 
|-
 
|-
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|uint]]  
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|uint]]  
−
| style='color: black; width: 90%; line-height: 1.0;' | '''CreateStopwatchTimer''' (const [[../BasicDataTypes|uint]] ''_uDisplayTextId'', const [[../BasicDataTypes|uint8]] ''_uFaction'' = kMaxFactions)
+
| style='color: black; width: 90%; line-height: 1.0;' | '''CreateStopwatchTimer''' (const [[../BasicDataTypes|uint]] ''_uDisplayTextId'', const [[../BasicDataTypes|uint8]] ''_uFaction'' = kMaxFactions, const [[../BasicDataTypes|string]]&in ''_sName'' = "")
 
|-
 
|-
 
|
 
|
Line 564: Line 656:
 
|
 
|
 
| style = 'color: #505050; line-height: 0.5;' |''focus the given player's camera on the given target''
 
| style = 'color: #505050; line-height: 0.5;' |''focus the given player's camera on the given target''
 +
|-
 +
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|bool]]
 +
| style='color: black; width: 90%; line-height: 1.0;' | '''IsCutScenePlaying''' () const
 +
|-
 +
|
 +
| style = 'color: #505050; line-height: 0.5;' |''is a cutscene currently playing?''
 
|-
 
|-
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]  
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]  
Line 570: Line 668:
 
|
 
|
 
| style = 'color: #505050; line-height: 0.5;' |''play the given cutscene''
 
| style = 'color: #505050; line-height: 0.5;' |''play the given cutscene''
 +
|-
 +
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]
 +
| style='color: black; width: 90%; line-height: 1.0;' | '''FadeToBlack''' (const [[../BasicDataTypes|uint8]] ''_Faction'', const [[../BasicDataTypes|uint8]] ''_uControlIndex'', const [[../BasicDataTypes|uint]] ''_uTimeMS'' = 1000)
 +
|-
 +
|
 +
| style = 'color: #505050; line-height: 0.5;' |''fade camera to black over the course of _uTimeMS milliseconds for the given player''
 +
|-
 +
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]
 +
| style='color: black; width: 90%; line-height: 1.0;' | '''FadeFromBlack''' (const [[../BasicDataTypes|uint8]] ''_Faction'', const [[../BasicDataTypes|uint8]] ''_uControlIndex'', const [[../BasicDataTypes|uint]] ''_uTimeMS'' = 1000)
 +
|-
 +
|
 +
| style = 'color: #505050; line-height: 0.5;' |''fade camera from black to regular view over the course of _uTimeMS milliseconds for the given player''
 +
|-
 +
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]
 +
| style='color: black; width: 90%; line-height: 1.0;' | '''FadeToBlackAndBack''' (const [[../BasicDataTypes|uint8]] ''_Faction'', const [[../BasicDataTypes|uint8]] ''_uControlIndex'', const [[../BasicDataTypes|uint]] ''_uFadeTimeMS'' = 1000, const [[../BasicDataTypes|uint]] ''_uStayTimeMS'' = 1000)
 +
|-
 +
|
 +
| style = 'color: #505050; line-height: 1.0;' |''fade camera to black over _uFadeTimeMS milliseconds, stay at full black for _uStayTimeMS milliseconds, then fade back into view over _uFadeTimeMS milliseconds again.''
 
|}
 
|}
  
 
==== Miscellaneous ====
 
==== Miscellaneous ====
−
Everything elese.
+
Everything else.
 
{| border='0' style ='border:solid 1px #eeeedd; color: black; width: 1200px;background-color: #ffffcc;' cellspacing='0' cellpadding='7'
 
{| border='0' style ='border:solid 1px #eeeedd; color: black; width: 1200px;background-color: #ffffcc;' cellspacing='0' cellpadding='7'
 +
|-
 +
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]
 +
| style='color: black; width: 90%; line-height: 1.0;' | '''RemoveEntity''' (const [[../Entity|Entity]]&in ''_Entity'')
 +
|-
 +
|
 +
| style = 'color: #505050; line-height: 0.5;' |''remove the given entity from the level permanently''
 +
|-
 +
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]
 +
| style='color: black; width: 90%; line-height: 1.0;' | '''CastSpell''' (const [[../BasicDataTypes|string]]&in ''_sSpellName'', const [[../BasicDataTypes|uint8]] ''_Faction'', const [[../Entity|Entity]]&in ''_Target'')
 +
|-
 +
|
 +
| style = 'color: #505050; line-height: 0.5;' |''cast spell on entity''
 
|-
 
|-
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]  
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]  
Line 611: Line 739:
 
|
 
|
 
| style = 'color: #505050; line-height: 1.0;' |''suspend or allow the automatic playing of combat music (e.g. during cutscenes, _Faction and _uControlIndex may be -1 if the music should be suspended for all players).''
 
| style = 'color: #505050; line-height: 1.0;' |''suspend or allow the automatic playing of combat music (e.g. during cutscenes, _Faction and _uControlIndex may be -1 if the music should be suspended for all players).''
 +
|-
 +
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]
 +
| style='color: black; width: 90%; line-height: 1.0;' | '''SuspendAmbientSounds''' (const [[../BasicDataTypes|uint8]] ''_Faction'', const [[../BasicDataTypes|uint8]] ''_uControlIndex'', const [[../BasicDataTypes|bool]] ''_bSuspend'')
 +
|-
 +
|
 +
| style = 'color: #505050; line-height: 0.5;' |''suspend or allow ambient sounds (_Faction and _uControlIndex may be -1 if the ambient sounds should be suspended for all players).''
 +
|-
 +
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]
 +
| style='color: black; width: 90%; line-height: 1.0;' | '''PlayVideo''' (const [[../BasicDataTypes|uint8]] ''_Faction'', const [[../BasicDataTypes|uint8]] ''_uControlIndex'', const [[../BasicDataTypes|string]]&in ''_sVideoName'', const [[../BasicDataTypes|bool]] ''_bShowCredits'' = false)
 +
|-
 +
|
 +
| style = 'color: #505050; line-height: 1.0;' |''play a video for the given player (_Faction and _uControlIndex may be -1 if the video should be played for all players). if _bShowCredits is true - well you can guess what happens''
 
|-
 
|-
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]  
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]  
Line 629: Line 769:
 
|
 
|
 
| style = 'color: #505050; line-height: 0.5;' |''activate the spawn of the given name''
 
| style = 'color: #505050; line-height: 0.5;' |''activate the spawn of the given name''
 +
|-
 +
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]
 +
| style='color: black; width: 90%; line-height: 1.0;' | '''ResetSpawn''' (const [[../BasicDataTypes|string]]&in ''_sName'')
 +
|-
 +
|
 +
| style = 'color: #505050; line-height: 0.5;' |''reset spawn to initial default state (including inactive if it is inactive by default)''
 
|-
 
|-
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]  
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]  
Line 653: Line 799:
 
|
 
|
 
| style = 'color: #505050; line-height: 0.5;' |''lock or unlock the given RTS technology for the given faction''
 
| style = 'color: #505050; line-height: 0.5;' |''lock or unlock the given RTS technology for the given faction''
 +
|-
 +
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|uint]]
 +
| style='color: black; width: 90%; line-height: 1.0;' | '''GetBaseSupply''' (const [[../BasicDataTypes|uint8]] ''_Faction'') const
 +
|-
 +
|
 +
| style = 'color: #505050; line-height: 0.5;' |''get baseline supply limit for the given faction (this will be provided to the faction in addition to any supply limit bonuses from sectors or buildings)''
 +
|-
 +
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]
 +
| style='color: black; width: 90%; line-height: 1.0;' | '''SetBaseSupply''' (const [[../BasicDataTypes|uint8]] ''_Faction'', const [[../BasicDataTypes|uint]] ''_uSupply'')
 +
|-
 +
|
 +
| style = 'color: #505050; line-height: 0.5;' |''set baseline supply limit for the given faction''
 
|-
 
|-
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]  
 
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]  
Line 677: Line 835:
 
|
 
|
 
| style = 'color: #505050; line-height: 0.5;' |''for debugging only! add action history of this creature to debug output. only works until DebugTrackActions is called on another creature.''
 
| style = 'color: #505050; line-height: 0.5;' |''for debugging only! add action history of this creature to debug output. only works until DebugTrackActions is called on another creature.''
 +
|-
 +
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]
 +
| style='color: black; width: 90%; line-height: 1.0;' | '''AutoSave''' ()
 +
|-
 +
|
 +
| style = 'color: #505050; line-height: 0.5;' |''trigger a manual autosave. NOTE: the autosave will not happen immediately but only at the start of the next tick!''
 +
|-
 +
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]
 +
| style='color: black; width: 90%; line-height: 1.0;' | '''UnlockAchievement''' (const [[../BasicDataTypes|uint8]] ''_uFaction'', const [[../BasicDataTypes|uint8]] ''_uControlIndex'', const [[../BasicDataTypes|string]]&in ''_sAchievementName'')
 +
|-
 +
|
 +
| style = 'color: #505050; line-height: 0.5;' |''unlock the given achievement''
 +
|-
 +
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]
 +
| style='color: black; width: 90%; line-height: 1.0;' | '''IncrementAchievementStat''' (const [[../BasicDataTypes|uint8]] ''_uFaction'', const [[../BasicDataTypes|uint8]] ''_uControlIndex'', const [[../BasicDataTypes|string]]&in ''_sStatName'')
 +
|-
 +
|
 +
| style = 'color: #505050; line-height: 0.5;' |''increment the given achievement-related stat''
 +
|-
 +
| style='color: blue; width: 10%; text-align:right;line-height: 0.8;' | [[../BasicDataTypes|void]]
 +
| style='color: black; width: 90%; line-height: 1.0;' | '''ResetAchievements''' (const [[../BasicDataTypes|uint8]] ''_uFaction'', const [[../BasicDataTypes|uint8]] ''_uControlIndex'')
 +
|-
 +
|
 +
| style = 'color: #505050; line-height: 0.5;' |''reset all achievements for the given player (only works in non-final builds, for obvious reasons)''
 
|-
 
|-
 
|}
 
|}

Latest revision as of 16:14, 14 May 2020

class LevelReference

The main interface for interacting with the level the player is currently in.

Class Methods

Getters

Functions allowing access to basic objects.
ATTENTION: In general, all functions prefixed with Find are computationally expensive and should be used sparingly.

uint GetCurrentTick () const
get the current tick
uint GetMapId () const
get the map index of the current level
World@ GetWorld ()
get world
Random@ GetRandom ()
get the random number generator
HeroParty@ GetHeroParty (const uint8 _uFaction)
get the hero party for the given faction
QuestJournal@ GetJournal (const uint8 _uFaction)
get the player's quest journal
uint GetNumberOfSectors () const
get number of sectors in the level
Sector@ GetSectorByName (const string&in _sName)
get sector script class by name
Sector@ GetSectorByIndex (const uint _uIndex)
get sector script class by index
Sector@[]@ GetSectorsByOwner (const uint8 _uFaction)
get all sectors owned by the given faction
Building GetFactionCapitol (const uint8 _uFaction)
get the capitol building of the given faction (may return an invalid building if they don't currently have a capitol)
Building GetBuildingByName (const string&in _sName)
get building by name
Building GetBuildingById (const uint _uId)
get building by id
Creature GetCreatureByName (const string&in _sName)
get creature by name
Creature GetCreatureById (const uint _uId)
get creature by id
LogicObject GetLogicObjectByName (const string&in _sName)
get logic object by name
LogicObject GetLogicObjectById (const uint _uId)
get logic object by id
ResourceDeposit GetResourceDepositByName (const string&in _sName)
get resource deposit by name
ResourceDeposit GetResourceDepositById (const uint _uId)
get resource deposit by id
Entity GetEntityById (const uint _uId)
get any entity (creature, building, etc.) by its id
Entity[]@ GetEntitiesByName (const string&in _sName)
get any entities with the given name. will return at most one entity of each type, as names must be unique within each entity type.
string FindEntityName (const Entity&in _Entity) const
find the script name for the given entity. returns an empty string if the entity has not been registered for script access.
Building[]@ FindBuildingsByDescription (const uint8 _uFaction, const string&in _sDescriptionName)
find all buildings with the given description currently owned by the given faction.
Building[]@ FindBuildingsByType (const uint8 _uFaction, const EBuildingType _Type)
find all buildings of the given type currently owned by the given faction.
Creature[]@ FindCreaturesByDescription (const uint8 _uFaction, const string&in _sDescriptionName)
find all creatures with the given description currently owned by the given faction.
Creature[]@ FindCreaturesByType (const uint8 _uFaction, const ECreatureType _Type)
find all creatures of the given type currently owned by the given faction.
Creature[]@ FindCreaturesByFaction (const uint8 _Faction, const bool _bControllableOnly = true)
get all creatures controlled by the given faction (if _bControllableOnly is false, non controllable creatures like workers and dead creatures will be excluded)
Creature[]@ GetCreaturesFromSpawn (const string&in _sSpawnName)
get all creatures spawned by the given spawn (does not include dead creatures!)
Entity[]@ GetEntitiesInGroup (const string&in _sName)
get all logic entities (creatures, buildings, logic objects, etc.) in the given group
bool CheckItemProperty (const string&in _sItemName, const EItemProperty _Property) const
check whether the given item property applies to the given item

Event Registration

Functions for registering event listener callbacks.

void RegisterHeroPartyEvent (const EHeroPartyEvent _EventType, TOnHeroPartyEvent@ _pFunction, const string&in _sTargetName, const uint8 _Faction)
register an event concerning the hero party
void RegisterInventoryEvent (const EInventoryEvent _EventType, TOnInventoryEvent@ _pFunction, const string&in _sTargetName, const uint8 _Faction)
register an event concerning the hero party's inventory
void RegisterCreatureInventoryEvent (const ECreatureInventoryEvent _EventType, TOnCreatureInventoryEvent@ _pFunction, const string&in _sTargetName, const uint8 _Faction)
register an event concerning the hero party's inventory specific to a creature
void RegisterCreatureEventByDescription (const ECreatureEvent _EventType, TOnCreatureEvent@ _pFunction, const string&in _sDescriptionName, const uint8 _Faction, const string&in _sParam = "")
register creature event by description name
void RegisterCreatureEventByIndividual (const ECreatureEvent _EventType, TOnCreatureEvent@ _pFunction, const string&in _sCreatureName, const string&in _sParam)
register creature event by individual creature name (e.g. name of the creature placed in the level editor OR unique hero name).

Please note, that this event can't be used, when the individual doesn't exist at the beginning of the map (for example when the creature spawns later).

void RegisterCreatureEventByIndividuals (const ECreatureEvent _EventType, TOnCreatureEvent@ _pFunction, const Creature[]&in _Creatures, const bool _bAnyCreature = false, const string&in _sParam = "")
register creature event by individual creature(s)
void RegisterBuildingEventByDescription (const EBuildingEvent _EventType, TOnBuildingEvent@ _pFunction, const string&in _sDescriptionName, const uint8 _Faction)
register building event by description name
void RegisterBuildingEventByIndividual (const EBuildingEvent _EventType, TOnBuildingEvent@ _pFunction, const string&in _sBuildingName)
register building event by individual building name (i.e. name of the building in the level editor)
void RegisterBuildingEventByIndividual (const EBuildingEvent _EventType, TOnBuildingEvent@ _pFunction, const Building&in _Building)
register building event by individual building instance
void RegisterBuildingEventByDescription (const EBuildingEvent _EventType, TOnBuildingExtendedEvent@ _pFunction, const string&in _sDescriptionName, const uint8 _Faction)
same as above, but receives extra information for certain event types
void RegisterBuildingEventByIndividual (const EBuildingEvent _EventType, TOnBuildingExtendedEvent@ _pFunction, const string&in _sBuildingName)
same as above, but receives extra information for certain event types
void RegisterBuildingEventByIndividual (const EBuildingEvent _EventType, TOnBuildingExtendedEvent@ _pFunction, const Building&in _Building)
same as above, but receives extra information for certain event types
void RegisterBuildingCreatureEventByDescription (const EBuildingCreatureEvent _EventType, TOnBuildingCreatureEvent@ _pFunction, const string&in _sDescriptionName, const uint8 _Faction)
register building event involving creatures by description name
void RegisterBuildingCreatureEventByIndividual (const EBuildingCreatureEvent _EventType, TOnBuildingCreatureEvent@ _pFunction, const string&in _sBuildingName)
register building event involving creatures by individual building name (i.e. name of the building in the level editor)
void RegisterBuildingCreatureEventByIndividual (const EBuildingCreatureEvent _EventType, TOnBuildingCreatureEvent@ _pFunction, const Building&in _Building)
register building event involving creatures by individual building instance
void RegisterLogicObjectEvent (const ELogicObjectEvent _EventType, TOnLogicObjectEvent@ _pFunction, const string&in _sObjectName, const uint8 _Faction)
register logic object event by individual object name (i.e. name of the logic object in the level editor). _Faction is the faction of the player causing the event.

If _Faction is >= kMaxFactions, the event will trigger independently of the causing faction.

void RegisterSectorEvent (const ESectorEvent _EventType, TOnSectorEvent@ _pFunction, const string&in _sSectorName)
register a sector event. if _sSectorName is specified and not empty, the event will be fired only for the given sector, otherwise it will be fired for all sectors.
void RegisterUIEvent (const EUIEvent _EventType, TOnUIEvent@ _pFunction, const uint8 _Faction)
register an event to be called when a certain event happens in the ui of the given faction's player
void RegisterUIEventByDescription (const EUIEvent _EventType, TOnUIEntityEvent@ _pFunction, const string&in _sDescriptionName, const uint8 _Faction)
register an event to be called when a certain event happens in the ui of the given faction's player
void RegisterUIEventByIndividual (const EUIEvent _EventType, TOnUIEntityEvent@ _pFunction, const string&in _sTargetName, const uint8 _Faction)
register an event to be called when a certain event happens in the ui of the given faction's player
void SetTimer (TOnTimerEvent@ _pFunction, const uint _uInterval)
register a timer event to be called after _uInterval seconds.
void SetTimer (TOnTimerUserDataEvent@ _pFunction, const uint _uInterval, const string&in _sUserData)
register a timer event to be called after _uInterval seconds.
void SetTimerMS (TOnTimerEvent@ _pFunction, const uint _uIntervalMS)
register a timer event to be called after _uInterval MILLIseconds.

NOTE: this timer is not 100% precise, it may be off by up to +/- 50 ms.

void SetTimerMS (TOnTimerUserDataEvent@ _pFunction, const uint _uIntervalMS, const string&in _sUserData)
register a timer event to be called after _uInterval MILLIseconds.

NOTE: this timer is not 100% precise, it may be off by up to +/- 50 ms.

void CancelTimer (TOnTimerEvent@ _pFunction)
cancel all currently registered timer events calling the given script function (does NOT include timers created using CreateCountdownTimer or CreateStopwatchTimer!)
void CancelTimer (TOnTimerUserDataEvent@ _pFunction, const string&in _sUserData)
cancel all currently registered timer events calling the given script function (does NOT include timers created using CreateCountdownTimer or CreateStopwatchTimer!)

Victory Conditions

Functions for controlling win/lose conditions.

bool HasWonGame (const uint8 _Faction) const
has the given faction won the game?
bool HasLostGame (const uint8 _Faction) const
has the given faction lost the game?
void WinGame (const uint8 _Faction)
show the victory screen to the given faction
void LoseGame (const uint8 _Faction)
show the defeat screen to the given faction
void ResetSuccessState (const uint8 _Faction)
reset success state (needed to fix faulty savegames)

Factions

Functions for controlling faction relations and assets.

uint8[]@ GetPlayerFactions () const
get a list of player controlled factions currently in the game (also counts AIs in player slots in a multiplayer game)
bool IsCampaignFactionInCombat () const
is the singleplayer default faction for this campaign map currently in combat? WARNING: only call this on campaign maps, never on a skirmish map!
ERace GetFactionRace (const uint8 _Faction) const
get the race of the given faction
void SetFactionRace (const uint8 _Faction, const ERace _Race)
set the race of the given faction. WARNING: DO NOT set the race to any race not yet present in the level. Otherwise you may cause considerable loading stutters when the faction produces buildings or units.
uint8 GetFactionColorId (const uint8 _Faction) const
get the color index used by the given faction
void SetFactionColorId (const uint8 _Faction, const uint8 _uColorId)
set the color index to be used by the given faciton
bool CanFactionUseGodstones (const uint8 _Faction) const
check whether the given faction can use godstones
void AllowGodstoneUse (const uint8 _Faction, const bool _bAllow)
allow a faction to use godstones (or don't)
void TransferFactionAssets (const uint8 _SourceFaction, const uint8 _DestinationFaction)
transfer ownership of all buildings and units of _uSourceFaction to _uDestFaction
void DestroyFactionAssets (const uint8 _Faction)
destroy or kill all buildings and creatures belonging to the given faction
void DamageFactionAssets (const uint8 _Faction)
apply damage to all buildings and creatures belonging to the given faction
EFactionRelation GetFactionRelation (const uint8 _FactionA, const uint8 _FactionB) const
get relation between the two given factions
void SetFactionRelation (const uint8 _FactionA, const uint8 _FactionB, const EFactionRelation _Relation)
set the relation between the two given factions.

Visibility

void AddVisibleSector (const uint8 _Faction, const uint _uSectorId)
Make a sector permanently visible for a specific faction.
void RemoveVisibleSector (const uint8 _Faction, const uint _uSectorId)
remove permanent visibility from sector
void AddVisiblePath (const uint8 _Faction, const string&in _sPathName)
make the shape described by a logic path permanently visible to the given faction
void RemoveVisiblePath (const uint8 _Faction, const string&in _sPathName)
remove permanent visibility of the given logic path shape

Notifications

Functions for displaying notifications to the player.

void ShowNotification (const uint8 _Faction, const string&in _sNotificationName, const Entity&in _Location)
show a one-off notification at the given location for the given faction.
void BeginNotification (const uint8 _Faction, const string&in _sNotificationName, const Entity&in _Location)
begin an ongoing notification at the given location for the given faction.
void EndNotification (const uint8 _Faction, const string&in _sNotificationName, const Entity&in _Location)
end an ongoing notification at the given location for the given faction.
void ShowQuestNotification (const uint8 _Faction, const string&in _sNotificationName, const string&in _sQuestName, const string&in _sTaskName)
show quest-related notification
void ShowExplorationBanner (const uint8 _Faction, const uint _uTextId, const string&in _sTextureName, const uint _uFadeInTime, const uint _uDisplayTime, const uint _uFadeOutTime, const string&in _sSoundName = "")
show exploration banner (times are in ms)

Onscreen Timers

Functions to display timers for certain events on the player's screen

uint CreateCountdownTimer (const uint _uDisplayTextId, const uint _uSeconds, TOnTimerEvent@ _pFunction = null, const uint8 _uFaction = kMaxFactions, const string&in _sName = "")
create a timer visible in the UI along with the text specified by Timer[_uDisplayTextId] (see names.xml).

the timer will count down from _uSeconds to 0 and optionally call _pFunction upon reaching 0. if _Faction is specified, the timer will only be displayed for the given faction. returns a unique id you can store in order to access the timer later on.

uint CreateCountdownTimerMS (const uint _uDisplayTextId, const uint _uMilliSeconds, TOnTimerEvent@ _pFunction = null, const uint8 _uFaction = kMaxFactions, const string&in _sName = "")
same as CreateCountdownTimer, but allows more precise time specification.

NOTE: The actual time the timer takes to finish may be off by up to +/- 50 ms.

uint CreateStopwatchTimer (const uint _uDisplayTextId, const uint8 _uFaction = kMaxFactions, const string&in _sName = "")
create a timer visible in the UI along with the text specified by Timer[_uDisplayTextId] (see names.xml).

the timer will steadily count up from 0 until it is removed. if _Faction is specified, the timer will only be displayed for the given faction. returns a unique id you can store in order to access the timer later on.

void PauseTimer (const uint _uTimerId, const bool _bPause = true)
pause or unpause the given timer
bool ModifyTimer (const uint _uTimerId, const int _iSeconds)
modify the current tick count of _uTimerId by _iSeconds. returns true if the timer is still valid, false if it has been removed
bool ModifyTimerMS (const uint _uTimerId, const int _iMilliSeconds)
modify the current tick count of _uTimerId by _iMilliSeconds. returns true if the timer is still valid, false if it has been removed
void RemoveTimer (const uint _uTimerId)
remove the timer with the given id
uint GetTimerTime (const uint _uTimerId) const
get the current time on the timer with the given id in seconds
uint GetTimerTimeMS (const uint _uTimerId) const
get the current time on the timer with the given id in MILLIseconds
bool IsTimerPaused (const uint _uTimerId) const
is the timer with the given id currently paused?

Tutorials

Functions for controlling tutorials.

void ShowTutorial (const uint8 _Faction, const string&in _sTutorialName)
show the given tutorial, provided that it has not already been shown.
void ShowTutorial (const uint8 _Faction, const string&in _sTutorialName, const Entity&in _Target)
show the given tutorial, provided that it has not already been shown.

Camera Manipulation

Functions for manipulating the player's point of view.

void SetMaxCameraDistance (const uint8 _Faction, const uint _uDistance)
set how far the given player's camera is allowed to zoom out
void ResetMaxCameraDistance (const uint8 _Faction)
reset the maximum camera distance to the level's default value
void SetCameraZoomPercent (const uint8 _Faction, const uint8 _uPercent)
set the given player's camera zoom to the given level (0 = fully zoomed in, 100 = fully zoomed out)
void FocusCamera (const uint8 _Faction, const Entity&in _Target)
focus the given player's camera on the given target
bool IsCutScenePlaying () const
is a cutscene currently playing?
void PlayCutScene (const string&in _sCutSceneName)
play the given cutscene
void FadeToBlack (const uint8 _Faction, const uint8 _uControlIndex, const uint _uTimeMS = 1000)
fade camera to black over the course of _uTimeMS milliseconds for the given player
void FadeFromBlack (const uint8 _Faction, const uint8 _uControlIndex, const uint _uTimeMS = 1000)
fade camera from black to regular view over the course of _uTimeMS milliseconds for the given player
void FadeToBlackAndBack (const uint8 _Faction, const uint8 _uControlIndex, const uint _uFadeTimeMS = 1000, const uint _uStayTimeMS = 1000)
fade camera to black over _uFadeTimeMS milliseconds, stay at full black for _uStayTimeMS milliseconds, then fade back into view over _uFadeTimeMS milliseconds again.

Miscellaneous

Everything else.

void RemoveEntity (const Entity&in _Entity)
remove the given entity from the level permanently
void CastSpell (const string&in _sSpellName, const uint8 _Faction, const Entity&in _Target)
cast spell on entity
void ShowWindow (const uint8 _Faction, const uint8 _uControlIndex, const EUIWindow _Window)
open up the specified window for the given player
void PlaySound (const uint8 _Faction, const uint8 _uControlIndex, const string&in _sSoundName, const Entity&in _Location = Entity ( ))
play a sound for the given player (_Faction and _uControlIndex may be -1 if the sound should be played for all players). _Location must only be specified for 3D sounds.
void StopSound (const uint8 _Faction, const uint8 _uControlIndex, const string&in _sSoundName, const Entity&in _Location = Entity ( ))
stop a sound for the given player (_Faction and _uControlIndex may be -1 if the sound should be played for all players). _Location must be the same one specified when starting the sound.
void SetGlobalSoundTrack (const uint8 _Faction, const uint8 _uControlIndex, const ESoundTrack _Track, const string&in _sSoundName)
override the sound event played in the given global event track (_Faction and _uControlIndex may be -1 if the track should be changed for all players). if _sSoundEventName is empty, the default track will be played again.
void SetGlobalSoundParameter (const uint8 _Faction, const uint8 _uControlIndex, const string&in _sParameterName, const int _iValue)
set the value of the given parameter for global sound events (_Faction and _uControlIndex may be -1 if the parameter should be changed for all players).
void SuspendAutomaticCombatMusic (const uint8 _Faction, const uint8 _uControlIndex, const bool _bSuspend)
suspend or allow the automatic playing of combat music (e.g. during cutscenes, _Faction and _uControlIndex may be -1 if the music should be suspended for all players).
void SuspendAmbientSounds (const uint8 _Faction, const uint8 _uControlIndex, const bool _bSuspend)
suspend or allow ambient sounds (_Faction and _uControlIndex may be -1 if the ambient sounds should be suspended for all players).
void PlayVideo (const uint8 _Faction, const uint8 _uControlIndex, const string&in _sVideoName, const bool _bShowCredits = false)
play a video for the given player (_Faction and _uControlIndex may be -1 if the video should be played for all players). if _bShowCredits is true - well you can guess what happens
void CallWeatherScript (const string&in _sFunction)
call the given function in the level's weather script
void BlockNavMesh (const string&in _sName, const bool _bBlocked)
activate or deactivate the nav blocker with the given name
void ActivateSpawn (const string&in _sName, const bool _bActive)
activate the spawn of the given name
void ResetSpawn (const string&in _sName)
reset spawn to initial default state (including inactive if it is inactive by default)
void ActivateAI (const uint8 _Faction)
activate an existing AI for the given faction
void SetAIFlag (const uint8 _Faction, const EAIFlag _Flag, const bool _bValue)
set the given flag for the given AI
bool IsTechnologyUnlocked (const uint8 _Faction, const string&in _sTechnologyName)
check whether the given RTS technology is currently unlocked for the given faction
void UnlockTechnology (const uint8 _Faction, const string&in _sTechnologyName, const bool _bUnlock = true)
lock or unlock the given RTS technology for the given faction
uint GetBaseSupply (const uint8 _Faction) const
get baseline supply limit for the given faction (this will be provided to the faction in addition to any supply limit bonuses from sectors or buildings)
void SetBaseSupply (const uint8 _Faction, const uint _uSupply)
set baseline supply limit for the given faction
void EnableLight (const string&in _sName, const bool _bEnable)
enable or disable the given light
void EnableGroup (const string&in _sName, const bool _bEnable)
enable/disable everything in the given group (including purely visual entities and light sources)
void ExecuteConsoleCommand (const string&in _sCommand)
execute the given console command (logic level prefix is included implicitly)
void DebugTrackActions () const
for debugging only! add action history of this creature to debug output. only works until DebugTrackActions is called on another creature.
void AutoSave ()
trigger a manual autosave. NOTE: the autosave will not happen immediately but only at the start of the next tick!
void UnlockAchievement (const uint8 _uFaction, const uint8 _uControlIndex, const string&in _sAchievementName)
unlock the given achievement
void IncrementAchievementStat (const uint8 _uFaction, const uint8 _uControlIndex, const string&in _sStatName)
increment the given achievement-related stat
void ResetAchievements (const uint8 _uFaction, const uint8 _uControlIndex)
reset all achievements for the given player (only works in non-final builds, for obvious reasons)

class LevelReference

The main interface for interacting with the level the player is currently in.

Class Methods

Getters

Functions allowing access to basic objects.
ATTENTION: In general, all functions prefixed with Find are computationally expensive and should be used sparingly.

uint GetCurrentTick () const
get the current tick
uint GetMapId () const
get the map index of the current level
World@ GetWorld ()
get world
Random@ GetRandom ()
get the random number generator
HeroParty@ GetHeroParty (const uint8 _uFaction)
get the hero party for the given faction
QuestJournal@ GetJournal (const uint8 _uFaction)
get the player's quest journal
uint GetNumberOfSectors () const
get number of sectors in the level
Sector@ GetSectorByName (const string&in _sName)
get sector script class by name
Sector@ GetSectorByIndex (const uint _uIndex)
get sector script class by index
Sector@[]@ GetSectorsByOwner (const uint8 _uFaction)
get all sectors owned by the given faction
Building GetFactionCapitol (const uint8 _uFaction)
get the capitol building of the given faction (may return an invalid building if they don't currently have a capitol)
Building GetBuildingByName (const string&in _sName)
get building by name
Building GetBuildingById (const uint _uId)
get building by id
Creature GetCreatureByName (const string&in _sName)
get creature by name
Creature GetCreatureById (const uint _uId)
get creature by id
LogicObject GetLogicObjectByName (const string&in _sName)
get logic object by name
LogicObject GetLogicObjectById (const uint _uId)
get logic object by id
ResourceDeposit GetResourceDepositByName (const string&in _sName)
get resource deposit by name
ResourceDeposit GetResourceDepositById (const uint _uId)
get resource deposit by id
Entity GetEntityById (const uint _uId)
get any entity (creature, building, etc.) by its id
Entity[]@ GetEntitiesByName (const string&in _sName)
get any entities with the given name. will return at most one entity of each type, as names must be unique within each entity type.
string FindEntityName (const Entity&in _Entity) const
find the script name for the given entity. returns an empty string if the entity has not been registered for script access.
Building[]@ FindBuildingsByDescription (const uint8 _uFaction, const string&in _sDescriptionName)
find all buildings with the given description currently owned by the given faction.
Building[]@ FindBuildingsByType (const uint8 _uFaction, const EBuildingType _Type)
find all buildings of the given type currently owned by the given faction.
Creature[]@ FindCreaturesByDescription (const uint8 _uFaction, const string&in _sDescriptionName)
find all creatures with the given description currently owned by the given faction.
Creature[]@ FindCreaturesByType (const uint8 _uFaction, const ECreatureType _Type)
find all creatures of the given type currently owned by the given faction.
Creature[]@ FindCreaturesByFaction (const uint8 _Faction, const bool _bControllableOnly = true)
get all creatures controlled by the given faction (if _bControllableOnly is false, non controllable creatures like workers and dead creatures will be excluded)
Creature[]@ GetCreaturesFromSpawn (const string&in _sSpawnName)
get all creatures spawned by the given spawn (does not include dead creatures!)
Entity[]@ GetEntitiesInGroup (const string&in _sName)
get all logic entities (creatures, buildings, logic objects, etc.) in the given group
bool CheckItemProperty (const string&in _sItemName, const EItemProperty _Property) const
check whether the given item property applies to the given item

Event Registration

Functions for registering event listener callbacks.

void RegisterHeroPartyEvent (const EHeroPartyEvent _EventType, TOnHeroPartyEvent@ _pFunction, const string&in _sTargetName, const uint8 _Faction)
register an event concerning the hero party
void RegisterInventoryEvent (const EInventoryEvent _EventType, TOnInventoryEvent@ _pFunction, const string&in _sTargetName, const uint8 _Faction)
register an event concerning the hero party's inventory
void RegisterCreatureInventoryEvent (const ECreatureInventoryEvent _EventType, TOnCreatureInventoryEvent@ _pFunction, const string&in _sTargetName, const uint8 _Faction)
register an event concerning the hero party's inventory specific to a creature
void RegisterCreatureEventByDescription (const ECreatureEvent _EventType, TOnCreatureEvent@ _pFunction, const string&in _sDescriptionName, const uint8 _Faction)
register creature event by description name
void RegisterCreatureEventByIndividual (const ECreatureEvent _EventType, TOnCreatureEvent@ _pFunction, const string&in _sCreatureName, const string&in _sParam)
register creature event by individual creature name (e.g. name of the creature placed in the level editor OR unique hero name).

Please note, that this event can't be used, when the individual doesn't exist at the beginning of the map (for example when the creature spawns later).

void RegisterCreatureEventByIndividuals (const ECreatureEvent _EventType, TOnCreatureEvent@ _pFunction, const Creature[]&in _Creatures, const bool _bAnyCreature = false, const string&in _sParam = "")
register creature event by individual creature(s)
void RegisterBuildingEventByDescription (const EBuildingEvent _EventType, TOnBuildingEvent@ _pFunction, const string&in _sDescriptionName, const uint8 _Faction)
register building event by description name
void RegisterBuildingEventByIndividual (const EBuildingEvent _EventType, TOnBuildingEvent@ _pFunction, const string&in _sBuildingName)
register building event by individual building name (i.e. name of the building in the level editor)
void RegisterBuildingCreatureEventByDescription (const EBuildingCreatureEvent _EventType, TOnBuildingCreatureEvent@ _pFunction, const string&in _sDescriptionName, const uint8 _Faction)
register building event involving creatures by description name
void RegisterBuildingCreatureEventByIndividual (const EBuildingCreatureEvent _EventType, TOnBuildingCreatureEvent@ _pFunction, const string&in _sBuildingName)
register building event involving creatures by individual building name (i.e. name of the building in the level editor)
void RegisterLogicObjectEvent (const ELogicObjectEvent _EventType, TOnLogicObjectEvent@ _pFunction, const string&in _sObjectName, const uint8 _Faction)
register logic object event by individual object name (i.e. name of the logic object in the level editor). _Faction is the faction of the player causing the event.

If _Faction is >= kMaxFactions, the event will trigger independently of the causing faction.

void RegisterSectorEvent (const ESectorEvent _EventType, TOnSectorEvent@ _pFunction, const string&in _sSectorName)
register a sector event. if _sSectorName is specified and not empty, the event will be fired only for the given sector, otherwise it will be fired for all sectors.
void RegisterUIEvent (const EUIEvent _EventType, TOnUIEvent@ _pFunction, const uint8 _Faction)
register an event to be called when a certain event happens in the ui of the given faction's player
void RegisterUIEventByDescription (const EUIEvent _EventType, TOnUIEntityEvent@ _pFunction, const string&in _sDescriptionName, const uint8 _Faction)
register an event to be called when a certain event happens in the ui of the given faction's player
void RegisterUIEventByIndividual (const EUIEvent _EventType, TOnUIEntityEvent@ _pFunction, const string&in _sTargetName, const uint8 _Faction)
register an event to be called when a certain event happens in the ui of the given faction's player
void SetTimer (TOnTimerEvent@ _pFunction, const uint _uInterval)
register a timer event to be called after _uInterval seconds.
void SetTimerMS (TOnTimerEvent@ _pFunction, const uint _uIntervalMS)
register a timer event to be called after _uInterval MILLIseconds.

NOTE: this timer is not 100% precise, it may be off by up to +/- 50 ms.

void CancelTimer (TOnTimerEvent@ _pFunction)
cancel all currently registered timer events calling the given script function (does NOT include timers created using CreateCountdownTimer or CreateStopwatchTimer!)

Victory Conditions

Functions for controlling win/lose conditions.

void WinGame (const uint8 _Faction)
show the victory screen to the given faction
void LoseGame (const uint8 _Faction)
show the defeat screen to the given faction

Factions

Functions for controlling faction relations and assets.

uint8[]@ GetPlayerFactions () const
get a list of player controlled factions currently in the game (also counts AIs in player slots in a multiplayer game)
bool IsCampaignFactionInCombat () const
is the singleplayer default faction for this campaign map currently in combat? WARNING: only call this on campaign maps, never on a skirmish map!
ERace GetFactionRace (const uint8 _Faction) const
get the race of the given faction
uint8 GetFactionColorId (const uint8 _Faction) const
get the color index used by the given faction
void SetFactionColorId (const uint8 _Faction, const uint8 _uColorId)
set the color index to be used by the given faciton
void TransferFactionAssets (const uint8 _SourceFaction, const uint8 _DestinationFaction)
transfer ownership of all buildings and units of _uSourceFaction to _uDestFaction
void DestroyFactionAssets (const uint8 _Faction)
destroy or kill all buildings and creatures belonging to the given faction
void DamageFactionAssets (const uint8 _Faction)
apply damage to all buildings and creatures belonging to the given faction
EFactionRelation GetFactionRelation (const uint8 _FactionA, const uint8 _FactionB) const
get relation between the two given factions
void SetFactionRelation (const uint8 _FactionA, const uint8 _FactionB, const EFactionRelation _Relation)
set the relation between the two given factions.

Visibility

void AddVisibleSector (const uint8 _Faction, const uint _uSectorId)
Make a sector permanently visible for a specific faction.
void RemoveVisibleSector (const uint8 _Faction, const uint _uSectorId)
remove permanent visibility from sector
void AddVisiblePath (const uint8 _Faction, const string&in _sPathName)
make the shape described by a logic path permanently visible to the given faction
void RemoveVisiblePath (const uint8 _Faction, const string&in _sPathName)
remove permanent visibility of the given logic path shape

Notifications

Functions for displaying notifications to the player.

void ShowNotification (const uint8 _Faction, const string&in _sNotificationName, const Entity&in _Location)
show a one-off notification at the given location for the given faction.
void BeginNotification (const uint8 _Faction, const string&in _sNotificationName, const Entity&in _Location)
begin an ongoing notification at the given location for the given faction.
void EndNotification (const uint8 _Faction, const string&in _sNotificationName, const Entity&in _Location)
end an ongoing notification at the given location for the given faction.
void ShowExplorationBanner (const uint8 _Faction, const uint _uTextId, const string&in _sTextureName, const uint _uFadeInTime, const uint _uDisplayTime, const uint _uFadeOutTime, const string&in _sSoundName = "")
show exploration banner (times are in ms)

Onscreen Timers

Functions to display timers for certain events on the player's screen

uint CreateCountdownTimer (const uint _uDisplayTextId, const uint _uSeconds, TOnTimerEvent@ _pFunction = null, const uint8 _uFaction = kMaxFactions)
create a timer visible in the UI along with the text specified by Timer[_uDisplayTextId] (see names.xml).

the timer will count down from _uSeconds to 0 and optionally call _pFunction upon reaching 0. if _Faction is specified, the timer will only be displayed for the given faction. returns a unique id you can store in order to access the timer later on.

uint CreateCountdownTimerMS (const uint _uDisplayTextId, const uint _uMilliSeconds, TOnTimerEvent@ _pFunction = null, const uint8 _uFaction = kMaxFactions)
same as CreateCountdownTimer, but allows more precise time specification.

NOTE: The actual time the timer takes to finish may be off by up to +/- 50 ms.

uint CreateStopwatchTimer (const uint _uDisplayTextId, const uint8 _uFaction = kMaxFactions)
create a timer visible in the UI along with the text specified by Timer[_uDisplayTextId] (see names.xml).

the timer will steadily count up from 0 until it is removed. if _Faction is specified, the timer will only be displayed for the given faction. returns a unique id you can store in order to access the timer later on.

void PauseTimer (const uint _uTimerId, const bool _bPause = true)
pause or unpause the given timer
bool ModifyTimer (const uint _uTimerId, const int _iSeconds)
modify the current tick count of _uTimerId by _iSeconds. returns true if the timer is still valid, false if it has been removed
bool ModifyTimerMS (const uint _uTimerId, const int _iMilliSeconds)
modify the current tick count of _uTimerId by _iMilliSeconds. returns true if the timer is still valid, false if it has been removed
void RemoveTimer (const uint _uTimerId)
remove the timer with the given id
uint GetTimerTime (const uint _uTimerId) const
get the current time on the timer with the given id in seconds
uint GetTimerTimeMS (const uint _uTimerId) const
get the current time on the timer with the given id in MILLIseconds
bool IsTimerPaused (const uint _uTimerId) const
is the timer with the given id currently paused?

Tutorials

Functions for controlling tutorials.

void ShowTutorial (const uint8 _Faction, const string&in _sTutorialName)
show the given tutorial, provided that it has not already been shown.
void ShowTutorial (const uint8 _Faction, const string&in _sTutorialName, const Entity&in _Target)
show the given tutorial, provided that it has not already been shown.

Camera Manipulation

Functions for manipulating the player's point of view.

void SetMaxCameraDistance (const uint8 _Faction, const uint _uDistance)
set how far the given player's camera is allowed to zoom out
void ResetMaxCameraDistance (const uint8 _Faction)
reset the maximum camera distance to the level's default value
void SetCameraZoomPercent (const uint8 _Faction, const uint8 _uPercent)
set the given player's camera zoom to the given level (0 = fully zoomed in, 100 = fully zoomed out)
void FocusCamera (const uint8 _Faction, const Entity&in _Target)
focus the given player's camera on the given target
void PlayCutScene (const string&in _sCutSceneName)
play the given cutscene

Miscellaneous

Everything elese.

void ShowWindow (const uint8 _Faction, const uint8 _uControlIndex, const EUIWindow _Window)
open up the specified window for the given player
void PlaySound (const uint8 _Faction, const uint8 _uControlIndex, const string&in _sSoundName, const Entity&in _Location = Entity ( ))
play a sound for the given player (_Faction and _uControlIndex may be -1 if the sound should be played for all players). _Location must only be specified for 3D sounds.
void StopSound (const uint8 _Faction, const uint8 _uControlIndex, const string&in _sSoundName, const Entity&in _Location = Entity ( ))
stop a sound for the given player (_Faction and _uControlIndex may be -1 if the sound should be played for all players). _Location must be the same one specified when starting the sound.
void SetGlobalSoundTrack (const uint8 _Faction, const uint8 _uControlIndex, const ESoundTrack _Track, const string&in _sSoundName)
override the sound event played in the given global event track (_Faction and _uControlIndex may be -1 if the track should be changed for all players). if _sSoundEventName is empty, the default track will be played again.
void SetGlobalSoundParameter (const uint8 _Faction, const uint8 _uControlIndex, const string&in _sParameterName, const int _iValue)
set the value of the given parameter for global sound events (_Faction and _uControlIndex may be -1 if the parameter should be changed for all players).
void SuspendAutomaticCombatMusic (const uint8 _Faction, const uint8 _uControlIndex, const bool _bSuspend)
suspend or allow the automatic playing of combat music (e.g. during cutscenes, _Faction and _uControlIndex may be -1 if the music should be suspended for all players).
void CallWeatherScript (const string&in _sFunction)
call the given function in the level's weather script
void BlockNavMesh (const string&in _sName, const bool _bBlocked)
activate or deactivate the nav blocker with the given name
void ActivateSpawn (const string&in _sName, const bool _bActive)
activate the spawn of the given name
void ActivateAI (const uint8 _Faction)
activate an existing AI for the given faction
void SetAIFlag (const uint8 _Faction, const EAIFlag _Flag, const bool _bValue)
set the given flag for the given AI
bool IsTechnologyUnlocked (const uint8 _Faction, const string&in _sTechnologyName)
check whether the given RTS technology is currently unlocked for the given faction
void UnlockTechnology (const uint8 _Faction, const string&in _sTechnologyName, const bool _bUnlock = true)
lock or unlock the given RTS technology for the given faction
void EnableLight (const string&in _sName, const bool _bEnable)
enable or disable the given light
void EnableGroup (const string&in _sName, const bool _bEnable)
enable/disable everything in the given group (including purely visual entities and light sources)
void ExecuteConsoleCommand (const string&in _sCommand)
execute the given console command (logic level prefix is included implicitly)
void DebugTrackActions () const
for debugging only! add action history of this creature to debug output. only works until DebugTrackActions is called on another creature.
Retrieved from "http://sf3scripting.spellforce.com/index.php?title=Script/LevelReference&oldid=743"