[][src]Struct sulis_state::script::ScriptEntity

pub struct ScriptEntity {
    pub index: Option<usize>,
}

Represents a single entity for Lua scripts. Also can represent an invalid, non-existant entity in some cases. Many script functions pass a parent which is a script entity, and often targets, which is a ScriptEntitySet that a ScriptEntity can be extracted from.

state_end() -> AIState

Returns the AI state telling the caller to end the AI turn.

Examples

  function ai_action(parent, state)
    -- tell ai to end turn immediately
    return parent:state_end()
  end

state_wait(time: Int) -> AIState

Returns the AI state telling the caller to wait for the specified number of milliseconds (time) times the base animation time, and then call the AI again. See state_end

vis_dist() -> Float

Returns the currently visibility distance for this entity (how many tiles on the map it can see). This is dependant on the area that the entity is in.

add_ability(ability_id: String)

Adds the ability with the specified ID to this entity

remove_ability(ability_id: String)

Removes the ability with the specified ID from this entity

add_levels(class: String, levels: Int)

Adds the specified number of levels of the specified class to this entity

add_xp(amount: Int)

Adds the specified amount of XP to the entity. For adding XP to the party, you generally want to use game:add_party_xp(amount) instead.

add_to_party(show_portrait: Bool (Optional))

Adds this entity to the player's party. show_portrait is whether the entity shows up in the portraits area of the UI. Defaults to true.

set_disabled(disabled: Bool)

Sets this entity to disabled status or not. Disabled status is only checked when an entity is dead, so this is only useful from the campaign on_party_death script. Disabled party members will not be removed from the party, and will be set back to 1 hit point when combat ends. You can use this for custom death behavior in a campaign.

remove_from_party()

Removes this entity from the player's party

get_relationship(other: ScriptEntity) -> Int

Returns a positive 1 if this entity is friendly or neutral to the specified other entity, or a negative 1 if it is hostile.

is_hostile(other: ScriptEntity) -> Bool

Returns true if this entity is hostile to the specified entity, false otherwise

is_friendly(other: ScriptEntity) -> Bool

Returns true if this entity is friendly to the specified entity, false otherwise

get_faction() -> String

Returns the ID of the faction that this entity currently belongs to

set_faction(faction: String)

Sets this entity to the specified faction. Valid factions are currently Hostile, Neutral, or Friendly. Hostiles will attack the player and friendlies on sight, but will not engage neutrals.

set_flag(flag: String, value: String (Optional))

Sets a flag to be stored on this entity. This value will persist as part of the save game and can be used to store custom state. If the value is not specified, sets the flag exists (for querying with has_flag()), but does not neccessarily set a specific value.

add_num_flag(flag: String, value: Float)

Adds the specified value to the amount stored in the specified flag. If the flag is not currently present, sets the flag to the specified value.

get_flag(flag: String) -> String

Returns the value of the specified flag on this entity. Returns the lua value of Nil if the flag does not exist.

has_flag(flag: String) -> Bool

Returns true if the specified flag is set to any value on this entity, false otherwise

get_num_flag(flag: String) -> Float

Returns the numeric value of this flag set on this entity, or 0.0 if it has not been set.

clear_flag(flag: String)

Clears the flag from this entity, as if it had never been set. Works for both numeric and standard flags. If the flag had not previously been set, does nothing. After this method, has_flag(flag) will return false.

is_valid() -> Bool

Returns true if this ScriptEntity references a valid entity that can be queried and acted on, false otherwise.

is_dead() -> Bool

Returns true if this entity is dead (zero hit points), false otherwise. Dead entities cannot be currently interacted with in meaningful ways.

is_party_member() -> Bool

Returns true if this entity is a member of the player's party (or if it is the player), false otherwise.

use_ability(ability: ScriptAbility, allow_invalid: Bool (Optional)) -> Bool

The parent entity attempts to use the ability. Returns true if the ability use was successful, false if it was not. After activating, the script will often need to handle a targeter (depending on the ability), using the methods on ScriptInterface (the game object). If allow_invalid is set to true, the ability will fire even if the parent could not normally use it at this time.

use_item(item: ScriptUsableItem) -> Bool

Attempts to use the specified item. Returns true if the item use was successful, false if it was not. See use_ability.

swap_weapons() -> Bool

Attempts to swap weapons from the currently held weapon set to the alternate weapon slots. Returns true if this is succesful, false if it is not. The entity must have enough AP to complete the action.

abilities() -> ScriptAbilitySet

Returns the ScriptAbilitySet with all the abilities that this entity can potentially activate.

targets() -> ScriptEntitySet

Creates a ScriptEntitySet consisting of all possible targets for abilities or items used by this entity. This includes all known entities in the same area as the parent entity.

targets_from(targets: Table) -> ScriptEntitySet

Creates a ScriptEntitySet for this parent with the specified array-like table of targets as the targets. Allows the script complete control over the set of targets

has_effect_with_tag(tag: String) -> Bool

Returns true if this entity has one or more active effects with the specified tag, false otherwise.

get_effects_with_tag(tag: String) -> Table of ScriptAppliedEffect

Returns an array-like table containing all of the effects currently applied to this entity with the specified tag.

get_auras_with_tag(tag: String) -> Table of ScriptAppliedEffect

Returns an array-like table containing all auras owned by this entity with the specified tag. Note that this includes only owned auras, not auras from another entity that are affected this entity.

remove_effects_with_tag(tag: String)

Removes all currently active effects applied to this entity that have the specified tag.

create_effect(name: String, duration: Int (Optional)) -> ScriptEffect

Creates a new effect with the specified name and duration. If duration is not specified, it is infinite, and will remain until removed or deactivated for a mode. The effect will not be in effect until you call apply() on it.

create_surface(name: String, points: Table, duration: Int (Optional)) -> ScriptEffect

Creates a surface effect with this entity as the parent. This is a special case of create_effect, above. The effect must have apply() called in order to actually be put into effect. See ScriptEffect. The points used by this method is a table of tables with x and y elements. This can be constructed by hand, or obtained from a ScriptEntitySet as the affected_points.

create_image_layer_anim(duration: Floag (Optional)) -> ScriptImageLayerAnimation

Creates an image layer animation that will add (or override) image layers of the entity for the specified duraiton. If duration is not specified, the animation lasts forever or until the attached effect is removed.

create_scale_anim(duration: Float (Optional)) -> ScriptScaleAnimation

Creates a scale animation that will change the size of the entity by a factor, for the specified duration. If duration is not specified, the animation lasts forever or until the attached effect is removed.

create_subpos_anim(duration: Float (Optional)) -> ScriptSubposAnimation

Creates an entity subpos animation, that can be used to temporarily move the location of the entity with pixel accuracy on the screen, for the specified duration in seconds. The animation is set up with further calls before calling activate().

create_color_anim(duration: Float (Optional)) -> ScriptColorAnimation

Creates an entity color animation, which changes the primary and secondary colors of the parent entity. If duration is specified, lasts for that many seconds. Otherwise, will last forever, or more typically until the attached effect is removed.

`create_particle_generator(image: String, duration: Float (Optional)) ->

ScriptParticleGeneratorCreates a Particle Generator animation. Despite the name, can also be used for more traditional frame based animations by using a single particle (seecreate_anim. If duration` is specified, lasts for that number of seconds. Otherwise, will last forever, or more typically until the attached effect is removed. The specified image must be the ID of a defined image.

create_anim(image: String, duration: Float (Optional)) -> ScriptParticleGenerator

Creates a particle generator animation set up for a single particle frame based animation. The image should normally be the ID of a timer image with specified frames. The duration is in seconds, or not specified to make the animation repeat until the parent effect is removed (if there is one). The anim must have activate() called once setup is complete.

create_targeter(ability: ScriptAbility) -> TargeterData

Creates a new targeter for the specified ability. The ability's script will be used for all functions. This targeter can then be configured before calling activate() to put it into effect. Upon the user or ai script selecting a target, on_target_select is called.

create_targeter_for_item(item: ScriptItem) -> TargeterData

Creates a new targeter for the specified item. The item's script will be used for all functions. The targeter can then be configured before calling activate(). See create_targeter above.

`move_towards_entity(target: ScriptEntity, distance: Float (Optional), max_len: Int

(Optional)) -> BoolCauses this entity to attempt to begin moving towards the specifiedtarget. If this entity cannot move at all towards the desired target, returns false, otherwise, returns true and creates a move animation that will proceed to be run asynchronously. Optionally, a distance` can be specified which is the distance this entity should be within the target to complete the move. If no distance is specified, the entity attempts to move within attack range. Can optionally specify a maximum path distance.

move_towards_point(x: Float, y: Float, distance: Float (Optional)) -> Bool

Causes this entity to attempt to begin moving towards the specified point at x and y. If distance is specified, attempts to move within that distance of the point. Otherwise, attempts to move so the parent entity's coordinates are equal to the nearest integers to x and y. If the entity cannot move at all or a path cannot be found, this returns false. Otherwise, returns true and an asynchronous move animation is initiated.

dist_to_entity(target: ScriptEntity) -> Float

Computes the current euclidean distance to the specified target, in tiles. This should not be used for targeting purposes. Use the ScriptEntitySet's filtering methods instead.

dist_to_point(point: Table) -> Float

Computes the euclidean distance to the specified point, in tiles. Point is a table of the form {x: x_coord, y: y_coord}

has_ap_to_attack() -> Bool

Returns true if this entity has enough AP to issue a single attack, false otherwise.

is_within_touch_dist(target: ScriptEntity) -> Bool

Returns whether this entity is close enough to touch the specified target.

is_within_attack_dist(target: ScriptEntity) -> Bool

Returns whether this entity is close enough to attack the target with its current weapon.

has_visibility(target: ScriptEntity) -> Bool

Returns true if this entity can see the target, false otherwise.

can_move() -> Bool

Returns true if this entity can move at all (even 1 square), false otherwise.

teleport_to(dest: Table)

Instantly moves this entity to the dest, which is a table of the form { x: x_coord, y: y_coord }. Will not move the entity if the dest position is invalid (outside area bounds, impassable).

weapon_attack(target: ScriptEntity) -> ScriptHitKind

Immediately rolls a random attack against the specified target, using this entities stats vs the defender. Returns the hit type, one of crit, hit, graze, or miss.

'anim_weapon_attack(target: ScriptEntity, callback: CallbackData (Optional),

use_ap: Bool (Optional))Attempts to perform a standard weapon attack against thetarget. The attack is animated, so this method immediately returns but the attack happens asynchronously. Upon completion of the attack, the callback(if specified) is run. Ifuse_ap` is specified to false, no ap is deducted from the parent for the attack. By default, the standard amount of ap is deducted.

`special_attack(target: ScriptEntity, attack_kind: String, accuracy_kind: String,

min_damage: Float, max_damage: Float, ap_damage: Float, damage_kind: String)Immediately rolls a random non-standard attack against thetarget, using the specified parameters. See anim_special_attack`.

`anim_special_attack(target: ScriptEntity, attack_kind: String, accuracy_kind: String,

min_damage: Float, max_damage: Float, ap_damage: Float, damage_kind: String, callback: CallbackData (Optional))Animates a non standard attack against thetargetwith the specified parameters. AttackKind is one ofMelee, Ranged, or Spell, and determines which of the attackers attack types to use. AccuracyKind is one of Fortitude, Reflex, Will, or Dummyand determines which of the defenders defense stats to use. The amount of damage is rolled randomly, between themin_damageandmax_damage, with the specified (ap_damage`) amount of armor piercing. This damage is then compared against the defender's armor as normal. If specified, the callback is called after the animation completes. No ap is deducted for this attack.

remove()

Sets this entity to be removed (as if dead) on the next frame update. This method is called asynchronously, so the entity will not yet be removed immediately after this method.

`take_damage(attacker: ScriptEntity, min_damage: Float, max_damage: Float,

damage_kind: String, ap: Int (Optional))Causes this entity to take the specified amount of damage. Hit points are removed, based on this entity's armor. The damage is rolled randomly betweenmin_damageandmax_damage, with the specified (ap`) amount of armor piercing.

heal_damage(amount: Float)

Adds the specified number of hit points to this entity. The entity's maximum hit points cannot be exceeded in this way.

add_class_stat(stat: String, amount: Float)

Adds the specified amount of the specified stat for this entity. The entity's maximum class stat cannot be exceeded.

remove_class_stat(stat: String, amount: Float)

Removes the specified amount of the class stat for this entity.

get_overflow_ap() -> Int

Returns the current amount of overflow ap for this entity. This is AP that will become available as bonus AP (up to the maximum per round AP) on this entity's next turn.

change_overflow_ap(ap: Int)

Modifies the amount of available overflow ap for this entity. See get_overflow_ap.

set_subpos(x: Float, y: Float)

Sets the pixel precise position of this entity to the specified value. An entity should generally not be left with non-zero values for either x or y.

add_ap(amount: Int)

Adds the specified amount of AP to this entity. Keep in mind the display_ap factor that this amount is divided by for display purposes.

remove_ap(amount: Int)

Removes the specified amount of AP from this entity. Keep in mind the display_ap factor that this amount is divided by for display purposes.

base_class() -> String

Returns the ID of the base class of this entity, or the class that this entity took at level 1.

id() -> String

Returns the ID of this entity. This should be unique, but it is currently possible to have more than one entity with the same ID (the game does provide a warning in this case).

name() -> String

Returns the name of this entity.

has_ability(ability_id: String) -> Bool

Returns true if this entity possesses the ability with the specified ability_id, false otherwise.

get_abilities_with_group(group_id: String) -> Table<ScriptAbility>

Returns an array table with all the active abilities owned by this entity with the specified ability group.

get_ability(ability_id: String) -> ScriptAbility

Returns a ScriptAbility representing the ability with the specified ability_id. Throws an error if this entity does not possess the ability.

ability_level(ability: ScriptAbility) -> Int

Returns the level of the specified ability for this entity. This is zero if the entity does not possess the ability, one if it possesses just the base ability, and larger numbers depending on the number of upgrades possessed.

ability_level_from_id(ability_id: String) -> Int

Returns the level of the ability with the specified ID. See ability_level

has_active_mode() -> Bool

Returns true if this entity has at least one currently active mode ability, false otherwise.

get_active_mode() -> Bool

Returns the first active mode for this entity, if one exists.

stats() -> Table

Creates and returns a stats table for this entity. This includes all stats shown on the character sheet.

inventory() -> ScriptInventory

Returns a ScriptInventory object representing this entity's inventory.

race() -> String

Returns the ID of the race of this entity

image_layer_offset(layer: String) -> Table

Gets the image layer offset, in tiles for the given image layer for this entity. The table has members x and y with the offset value. The layer must be a valid ImageLayer, one of HeldMain, HeldOff, Ears, Hair, Beard, Head, Hands, Foreground, Torso, Legs, Feet, Background, Cloak, Shadow

size_str() -> String

Returns the ID of the size of this entity, i.e. 2by2 or 3by3.

location() -> Table

Returns a table with 'x', 'y', and 'area' entries for the location of this entity. This is more efficient than calling individual methods for each component.

area() -> String

Returns the ID of the area that this entity is currently located in

width() -> Int

Returns the width of this entity in tiles

height() -> Int

Returns the height of this entity in tiles

x() -> Int

Returns the x coordinate of this entity's position in tiles

y() -> Int

Returns the y coordinate of this entity's position in tiles

center_x() -> Float

Returns the position of this entity's center (x + width / 2) as a float.

center_y() -> Float

Returns the position of this entity's center (y + height / 2) as a float.

is_threatened() -> Bool

Returns whether or not this entity is currently threatened by a hostile with a melee weapon

is_threatened_by(target: ScriptEntity) -> Bool

Returns true if this entity is threatened by the speciied target with its melee weapon, false otherwise

Fields

index: Option<usize>

Implementations

impl ScriptEntity[src]

pub fn invalid() -> ScriptEntity[src]

pub fn new(index: usize) -> ScriptEntity[src]

pub fn from(entity: &Rc<RefCell<EntityState>>) -> ScriptEntity[src]

pub fn is_party_member(&self) -> bool[src]

pub fn check_not_equal(&self, other: &ScriptEntity) -> Result<()>[src]

pub fn try_unwrap_index(&self) -> Result<usize>[src]

pub fn try_unwrap(&self) -> Result<Rc<RefCell<EntityState>>>[src]

Trait Implementations

impl Clone for ScriptEntity[src]

impl Debug for ScriptEntity[src]

impl UserData for ScriptEntity[src]

Auto Trait Implementations

impl RefUnwindSafe for ScriptEntity

impl Send for ScriptEntity

impl Sync for ScriptEntity

impl Unpin for ScriptEntity

impl UnwindSafe for ScriptEntity

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

impl<T> From<T> for T[src]

impl<'lua, T> FromLua<'lua> for T where
    T: 'static + UserData + Clone
[src]

impl<'lua, T> FromLuaMulti<'lua> for T where
    T: FromLua<'lua>, 
[src]

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

impl<'lua, T> ToLua<'lua> for T where
    T: 'static + UserData + Send
[src]

impl<'lua, T> ToLuaMulti<'lua> for T where
    T: ToLua<'lua>, 
[src]

impl<T> ToOwned for T where
    T: Clone
[src]

type Owned = T

The resulting type after obtaining ownership.

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.

impl<V, T> VZip<V> for T where
    V: MultiLane<T>, 
[src]