Script/LevelReference
From SF3
Contents
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. |
Arena Game Mode
Functions for interacting with the arena game mode.
| EArenaState | GetArenaState () const |
| get state of currently ongoing arena campaign | |
| string | GetActiveArenaCampaign () const |
| get technical name of current arena campaign or empty string if none is active | |
| void | StartArena (const string&in _sCampaignName, const uint8[]&in _Factions, const string[]&in _SpawnPointNames, const EArenaGameMode _GameMode = EArenaGameMode :: Story) |
| start a new arena campaign.
_sCampaignName is the technical name of an arena campaign description in articy. _Factions is the list of all factions participating in the arena mode. _SpawnPointNames can contain the names of any logic box/logic placeholder from the level editor. | |
| void | StopArena () |
| stop current arena campaign |
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) |
