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 | |
| 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 | 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!) |
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 | 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 | 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 | 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! | |
| 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 | |
| void | SetFactionRelation (const uint8 _FactionA, const uint8 _FactionB, const EFactionRelation _Relation) |
| set the relation between the two given factions. |
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 | 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 | |
| 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 | |
| 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 | 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. |
