ESCItem

Extends: Area2D

Description

An ESCItem defines a (usually interactive) item in the game.

When interacting with an ESCItem, the game character will automatically walk to an ESCLocation that is created as a child of an ESCItem.

By selecting the “Is Exit” checkbox when you create an ESCItem node, Escoria will look for an :exit_scene event in the attached script file. Any commands you place in the :exit_scene event will be run when the player chooses to “use” the exit - for example, saying a goodbye, or running a cutscene. Place a change_scene command inside this event to move the character to the next room.

Constants

FORBIDDEN_CHARACTERS

const FORBIDDEN_CHARACTERS = "[\'\"]"

List of forbidden characters in global_ids

Members

global_id

var global_id: String

The global ID of this item

esc_script

var esc_script: String

The ASHES script for this item

camera_node

var camera_node: NodePath

The node that references the camera position and zoom if this item is used as a camera target

is_movable

var is_movable: bool

Whether this item is movable. A movable item will be scaled with the terrain and be moved with commands like teleport and turn_to.

dialog_color

var dialog_color: Color

Color used for dialogs if that item talks.

default_action

var default_action: String

Default action to use if object is not in the inventory.

actions_requiring_target_object

var actions_requiring_target_object: PackedStringArray

Actions in this list make the item act as a source object and wait for a second clicked target object before running the action, typically USE <X> WITH <Y> or GIVE <X> TO <Y>.

is_exit

var is_exit: bool

If enabled, the ASHES script may have an :exit_scene event to manage scene changes. For simple exits that do not require scripted actions, the ESCExit node may be preferred.

is_trigger

var is_trigger: bool

Defines this item as acting as a trigger if enabled. Allows using specific events (defined in trigger_in_verb and trigger_out_verb properties) in ASHES scripts.

trigger_in_verb

var trigger_in_verb: String

Event name that is activated when another item enters the area defined by the trigger item. By default, “trigger_in”.

trigger_out_verb

var trigger_out_verb: String

Event name that is activated when another item exits the area defined by the trigger item. By default, “trigger_out”.

is_interactive

var is_interactive: bool

Defines whether the player can interact with this item. If false, the item will not react to inputs and mouse hovers.

hover_enabled

var hover_enabled: bool

Defines whether Escoria will manage a specific hover behavior when the item is focused. All options below can be used together. This can also be expanded or overriden in your ESCGame implementation (in methods element_focused() and element_unfocused()).

hover_modulate

var hover_modulate: Color

If hover is enabled, applies this color modulation on the ESCItem sprite.

hover_texture

var hover_texture: Texture2D

If hover is enabled, replaces this ESCItem sprite texture by this one.

hover_shader

var hover_shader: ShaderMaterial

If hover is enabled, applies this shader to the ESCItem sprite.

player_orients_on_arrival

var player_orients_on_arrival: bool

Whether player character orients towards ‘interaction_angle’ as it arrives at the item’s interaction position.

interaction_angle

var interaction_angle: int

If ‘player_orients_on_arrival’ is enabled, let the player character turn to this angle when it arrives at the item’s interaction position.

default_action_inventory

var default_action_inventory: String

Default action to use if object is in the inventory

combine_is_one_way

var combine_is_one_way: bool

If enabled, combination must be done in the way it is written in ASHES script ie. :use ON_ITEM If disabled, combination will be tried in the other way.

use_from_inventory_only

var use_from_inventory_only: bool

If enabled, then the object must have been picked up before using it. Keep disabled for items in the background, such as buttons.

inventory_texture

var inventory_texture: Texture2D

The visual representation for this item when it’s in the inventory

inventory_texture_hovered

var inventory_texture_hovered: Texture2D

The visual representation for this item when it’s in the inventory and hovered

dont_apply_terrain_scaling

var dont_apply_terrain_scaling: bool

If enabled, terrain scaling will not be applied and node will remain at the scale set in the scene.

speed

var speed: int

Speed of this item if movable

v_speed_damp

var v_speed_damp: float

Speed damp of this item if movable

animations

var animations: ESCAnimationResource

Animations resource for the item (walking, idling…)

animation_player_node

var animation_player_node: NodePath

The node used to play animations

custom_data

var custom_data: Dictionary

Custom data dictionary to ease customization and custom command creation. Avoid name collision using proper key names.

animation_sprite

var animation_sprite: Variant

Reference to the animation node (null if none was found)

terrain

var terrain: ESCTerrain

Reference to the current terrain

collision

var collision: Node

Reference to this items collision shape node

Signals

mouse_entered_item

signal mouse_entered_item(item: Variant)

Emitted when the mouse has entered this item

Parameters

Name	Type	Description	Required?
item	`Variant`	Item that emitted the signal.	yes

mouse_exited_item

signal mouse_exited_item(item: Variant)

Emitted when the mouse has exited this item

Parameters

Name	Type	Description	Required?
item	`Variant`	Item that emitted the signal.	yes

mouse_left_clicked_item

signal mouse_left_clicked_item(global_id: Variant)

Emitted when the item was left clicked

Parameters

Name	Type	Description	Required?
global_id	`Variant`	ID of this item	yes

mouse_double_left_clicked_item

signal mouse_double_left_clicked_item(global_id: Variant)

Emitted when the item was double clicked

Parameters

Name	Type	Description	Required?
global_id	`Variant`	ID of this item	yes

mouse_right_clicked_item

signal mouse_right_clicked_item(global_id: Variant)

Emitted when the item was right clicked

Parameters

Name	Type	Description	Required?
global_id	`Variant`	ID of this item	yes

arrived

signal arrived(walk_context: Variant)

Emitted when the item walked to a destination

Parameters

Name	Type	Description	Required?
walk_context	`Variant`	The walk context of the command	yes

started_talking

signal started_talking()

Emitted when the item started talking.

stopped_talking

signal stopped_talking()

Emitted when the item stopped talking.

started_walking

signal started_walking()

Emitted when the item started walking.

stopped_walking

signal stopped_walking()

Emitted when the item stopped walking.

Methods

connect_trigger_events

func connect_trigger_events() -> void

For trigger items, enable monitoring to detect collisions.

Parameters

None.

Returns

Returns nothing.

validate_exported_parameters

func validate_exported_parameters() -> void

Validates the various exported parameters so we get immediate crash.

Parameters

None.

Returns

Returns nothing.

disconnect_trigger_events

func disconnect_trigger_events() -> void

For trigger items, disable monitoring to disable collisions detection.

Parameters

None.

Returns

Returns nothing.

validate_animations

func validate_animations(animations_resource: ESCAnimationResource) -> void

Validates the ESCAnimationResource if it exists. Note that we pass in the ESCAnimationResource as an argument so that it can also be used to validate an ESCAnimationResource prior to being set.

Parameters

Name	Type	Description	Required?
animations_resource	`ESCAnimationResource`	Animation resource to validate before using it on this item.	yes

Returns

Returns nothing.

set_animations

func set_animations(p_animations: ESCAnimationResource) -> void

Setter for the animations property.

Parameters

Name	Type	Description	Required?
p_animations	`ESCAnimationResource`	the ESCAnimationResource to set.	yes

Returns

Returns nothing.

get_animation_player

func get_animation_player() -> Node

The animation player node

Parameters

None.

Returns

Returns the animation player node. (Node)

get_interact_position

func get_interact_position() -> Vector2

Return the position the player needs to walk to to interact with this item. That can either be a direct Position2D child or a collision shape

Parameters

None.

Returns

Returns a Vector2 value. (Vector2)

mouse_entered

func mouse_entered() -> void

React to the mouse entering the item by emitting the respective signal

Parameters

None.

Returns

Returns nothing.

do_mouse_exited

func do_mouse_exited() -> void

React to the mouse exiting the item by emitting the respective signal

Parameters

None.

Returns

Returns nothing.

teleport

func teleport(target: Node) -> void

Use the movable node to teleport this item to the target item

Parameters

Name	Type	Description	Required?
target	`Node`	Target node to teleport to	yes

Returns

Returns nothing.

teleport_to

func teleport_to(target: Vector2) -> void

Use the movable node to teleport this item to the target position

Parameters

Name	Type	Description	Required?
target	`Vector2`	Vector2 position to teleport to	yes

Returns

Returns nothing.

walk_to

func walk_to(pos: Vector2, p_walk_context: ESCWalkContext) -> void

Use the movable node to make the item walk to the given position

Parameters

Name	Type	Description	Required?
pos	`Vector2`	Position to walk to	yes
p_walk_context	`ESCWalkContext`	Walk context to use	no

Returns

Returns nothing.

stop_walking_now

func stop_walking_now(to_target: bool) -> void

Stop the movable node immediately and remain where it is at this moment, or teleport it directly at destination position if ‘to_target’ is true.

Parameters

Name	Type	Description	Required?
to_target	`bool`	if true, the movable node is teleport directly at its target destination	no

Returns

Returns nothing.

set_velocity

func set_velocity(speed_value: int) -> void

Set the moving speed

Parameters

Name	Type	Description	Required?
speed_value	`int`	Set the new speed	yes

Returns

Returns nothing.

has_moved

func has_moved() -> bool

Checks whether this item moved

Parameters

None.

Returns

Returns a bool value. (bool)

has_sprite

func has_sprite() -> bool

Checks whether this item has a sprite.

Parameters

None.

Returns

Returns a bool value. (bool)

get_sprite

func get_sprite() -> Node

Return the sprite node.

Parameters

None.

Returns

Returns a Node value. (Node)

set_angle

func set_angle(deg: int, wait: float) -> void

Set the angle

Parameters

Name	Type	Description	Required?
deg	`int`	The angle degree to set	yes
wait	`float`	Wait this amount of seconds until continuing with turning around	no

Returns

Returns nothing.

set_direction

func set_direction(direction_id: int, wait: float) -> void

Set the direction id

Parameters

Name	Type	Description	Required?
direction_id	`int`	The direction id	yes
wait	`float`	Wait this amount of seconds until continuing with turning around	no

Returns

Returns nothing.

turn_to

func turn_to(object: Node, wait: float) -> void

Turn to face another object

Parameters

Name	Type	Description	Required?
object	`Node`	Node whose position the item should face.	yes
wait	`float`	Optional delay in seconds before execution continues after turning.	no

Returns

Returns nothing.

check_talk_possible

func check_talk_possible() -> bool

Check everything is in place to play talk animations. A warning indicating the problem is printed in console, if necessary.

Parameters

None.

Returns

Returns a bool value. (bool)

start_talking

func start_talking() -> void

Play the talking animation

Parameters

None.

Returns

Returns nothing.

stop_talking

func stop_talking() -> void

Stop playing the talking animation

Parameters

None.

Returns

Returns nothing.

update_idle

func update_idle() -> void

Replay the last idle animation

Parameters

None.

Returns

Returns nothing.

get_camera_node

func get_camera_node() -> Node

Return the camera position if a camera_position_node exists or the global position of the player

Parameters

None.

Returns

Returns a Node value. (Node)

is_moving

func is_moving() -> bool

Whether the item is currently moving.

Parameters

None.

Returns

Returns true if the player is currently moving, false otherwise. (bool)

get_directions_quantity

func get_directions_quantity() -> int

The number of defined animation directions for this ESCItem.

Parameters

None.

Returns

Returns the number of defined animation directions for this ESCItem. (int)

get_custom_data

func get_custom_data() -> Dictionary

A Dictionary containing custom data defined for this ESCItem.

Parameters

None.

Returns

Returns a Dictionary containing custom data defined for this ESCItem. (Dictionary)

set_custom_data

func set_custom_data(data: Dictionary) -> void

Sets the custom_data Dictionary containing custom data defined for this ESCItem.

Parameters

Name	Type	Description	Required?
data	`Dictionary`	Custom data dictionary to assign to this item (an empty dictionary is used when `null`).	yes

Returns

Returns nothing.

ESCItem

Description

Constants

FORBIDDEN_CHARACTERS

Members

global_id

esc_script

camera_node

tooltip_name

is_movable

dialog_color

default_action

actions_requiring_target_object

is_exit

is_trigger

trigger_in_verb

trigger_out_verb

is_interactive

hover_enabled

hover_modulate

hover_texture

hover_shader

player_orients_on_arrival

interaction_angle

default_action_inventory

combine_is_one_way

use_from_inventory_only

inventory_texture

inventory_texture_hovered

dont_apply_terrain_scaling

speed

v_speed_damp

animations

animation_player_node

custom_data

animation_sprite

terrain

collision

Signals

mouse_entered_item

Parameters

mouse_exited_item

Parameters

mouse_left_clicked_item

Parameters

mouse_double_left_clicked_item

Parameters

mouse_right_clicked_item

Parameters

arrived

Parameters

started_talking

stopped_talking

started_walking

stopped_walking

Methods

connect_trigger_events

Parameters

Returns

validate_exported_parameters

Parameters

Returns

disconnect_trigger_events

Parameters

Returns

validate_animations

Parameters

Returns

set_animations

Parameters

Returns

get_animation_player

Parameters

Returns

get_interact_position

Parameters

Returns

mouse_entered

Parameters

Returns