SCUMM 8 API: Functions

User-Defined Functions

startup_script()

The script to be run on game start-up. Override this function to do all of your game initialisation. For example: set the starting room.

Camera Functions

camera_at(val)

Position the camera centrally at the following x pos.

camera_follow(actor)

Set the camera to follow the specified actor.

For example: camera_follow(selected_actor)

camera_pan_to(val)

Automatically pan the camera from it's current position to the position specified (can be an x-pos, or an object/actor).

For example: camera_pan_to(door2)

wait_for_camera()

Use this to "pause" the current script until the camera has finishing panning to target position.

cutscene(type, func_cutscene, func_override)

Start a cut-scene. Cutscenes allow for automated scripting of action, such as talking, movement and room transitions.

Parameters

• type(number) - The type of cutscene to use. There are three types of cutscenes:
  • 1 = No verbs
    • This removes the interface during the cut-scene. On exiting the cut-scene the camera is following the selected-actor.
  • 2 = Quick-cut
    • This leaves the verbs on the screen but still turns off the cursor.
  • 3 = No verbs & no follow
    • This component of cut-scene is the same as the no-verbs section with the exception that the camera does not auto-follow the selected-actor afterwards.
• func_cutscene(function) - The function/script to run as cutscene.
• func_override(function, OPTIONAL) - The function/script to run if/when the user skips the main cutscene. Typically, this code would simply position all objects/actors and state as they would appear had the user let the cutscene run its course. Also remember to stop music/sfx, if applicable.

For example:

cutscene(
   1, -- no verbs
   function()
	camera_at(144)
	camera_pan_to(selected_actor)
	wait_for_camera()
	say_line("wow! look at that old house:i wonder if anyone's home...")
   end
)

Actor Talk Functions

wait_for_message()

Pause current script execution until the currently-displayed message finishes its time-out.

(Note: This is automatically called by default when using say_line() or print_line())

say_line(actor, msg, use_caps, duration)

This command prints a line to the screen and causes the speaker's mouth to animate for the duration of the printed text display.

Parameters

• actor(table, OPTIONAL) - The talking actor (Default = selected_actor)
• msg(string) - The text to be spoken.
• use_caps(boolean, OPTIONAL) - Whether or not to display text in ALL CAPITALS (Default = false).
• duration(boolean, OPTIONAL) - The duration that the message will display for (Default = Auto-calculated by length of msg).

For example:

say_line(purp_tentacle, "stop!:come back here!", true)

stop_talking()

Stop everyone talking & remove displayed text.

print_line(msg, x, y, col, align, use_caps, duration, big_font)

This command prints a string to the screen. Used for messages from non-actors (e.g. a PA system or when there are no actors present).

• msg(string) - The text to be spoken.
• x/y(number) - The x and y position to display the text.
• col(number, OPTIONAL) - The color to use for the text (Default = 7 / White).
• align(number, OPTIONAL) - The type of alignment to use for the text block.
  • 0 = No Alignment (Default)
  • 1 = Center-align
• use_caps(boolean, OPTIONAL) - Whether or not to display text in ALL CAPITALS (Default = false).
• duration(boolean, OPTIONAL) - The duration that the message will display for (Default = Auto-calculated by length of msg).
• big_font(boolean, OPTIONAL) - Whether or not to display text using BIG font (Default = false).

Punctuation

The following characters can be used within the msg parameter to perform useful actions:

• ":" = New line, shown after current text prior expires
• ";" = New line, shown immediately

(Note: an Actor's talk animation is not activated with print_line() as it is with say-line()) For example:

print_line("deep in the caribbean:on the isle of thimbleweed!", 64, 45, 8, 1, true)

Dialog Options Functions

Functions relating to giving the user choices of what to say in a dialog exchange with another Actor/Object.

dialog_clear()

Clears any previous dialog options (used when talking between actors).

dialog_set(msg_table)

Specify the list of selectable text for the current list of dialog options.

-- build dialog options
dialog_set({ 
        "why did you stop me?",
	"where am i?",
	"who are you?",
	"nevermind"
})

dialog_add(msg)

Adds line of selectable text to the current list of dialog options.

dialog_start(col, hl_col)

Starts an dialog session, which will present the user with the current list of dialog statements to choose from. This is typically seen when a player is "talking" to an Actor. The statements are displayed using the col color specified by default, then switch to hl_col when the cursor is hovering a statement. Typically, you would then loop while waiting for an option to be selected. For example:

dialog_start(selected_actor.col, 7)
-- wait for selection
while not selected_sentence do break_time() end

dialog_hide()

This will temporarily hide the current dialog, without losing the current statements. This is typically run after selecting a statement, but allows you to re-run dialog_start again later to re-display current dialog options.

dialog_end()

This will indicate the end of a dialog session, returning back to previous game mode (or whatever the script defines next).

Actor/Object Functions

walk_to(actor, x, y)

Walk actor to the x and y position specified. If the target position is "walkable", the actor will find the shortest possible path and start walking. If the target position is not "walkable", the actor will attempt to walk as close to it as possible.

For example:

walk_to(selected_actor, other_actor.x - 8, other_actor.y)

wait_for_actor(actor)

This command waits before running the next line of code until the actor gets to its destination. For example, to wait until an actor walks to a target position before continuing code execution.

stop_actor(actor)

Stops an actor moving and clears any current animation. If they were walking, they stop on the spot and/or if they were playing an animation, they go back to "idle".

put_at(obj_or_actor, x, y, room)

Places an object or actor immediately at the specified room's x and y position. The room parameter should be omitted if just moving an object within the same room.

do_anim(actor/obj, cmd_type, cmd_value)

Perform an animation cycle for a specified Actor/Object. Can be used to play an animation (table of sprite numbers) for the specified Actor/Object. Alternatively, specifying the "face_towards" param with an Actor, will animate them to turn and face a specified target direction.

For example:

do_anim(selected_actor, anim_dancing)
do_anim(selected_actor, "face_towards", "face_front")

pickup_obj(obj)

This command picks up an object, puts it into the selected-actor's inventory (setting them as the object's owner) and removes the object from any room it was previously in.

get_use_pos(obj)

Returns the defined (or default) position that an Actor should be in to "use" it. For example, where to stand in a doorway before passing through. Typically, this wouldn't need to be called directly, as walking to or using objects in SCUMM-8 will use this value automatically.

Helper Functions

open_door(door_obj1, door_obj2)

Open one (or more) doors, by changing their state to "state_open". As doors tend to always have a counterpart (the door you enter in Room A, and the door you exit in Room B), this helper function makes it easy to keep paired doors' state in sync.

For example: open_door(me, obj_front_door_inside)

close_door(door_obj1, door_obj2)

Close one (or more) doors. Just like above, but the opposite!

proximity(obj_or_actor, obj_or_actor)

Returns the distance between two actors/objects (as a number).

valid_verb(verb, object)

Returns whether or not the specified verb is supported (e.g. has been defined) on the specified object/actor.

fades(fade, dir)

Perform a fade transition.

Parameters

• fade(number) - The type of fade transition to use.
  • Currently there is only one transition: "iris" (1), which closes to black like a camera shutter.
• dir(number) - The direction to fade in/out
  • 1 = Fade down
  • -1 = Fade up

For example:

-- fade out, using "iris" transition
fades(1, 1)

shake(enabled)

If enabled/true, performs a screen-shake effect until called again with a false parameter.

Room Functions

come_out_door(from_door, to_door, fade_effect)

This command is used to:

1. Change rooms,
2. Place the selected-actor at the door in a new room and also
3. (optionally) Perform a fade/transition effect. This helper function will also automatically check the state of the from_door to ensure it is open before you can enter it. For example:

-- exit the hallway to the front door, and perform an "iris" fade out/in
come_out_door(obj_hall_door, obj_front_door, 1)

change_room(new_room, fade)

This command changes the camera to a new room. In the process it causes the exit() code from the last room to be run and then the enter() code in the new room. Optionally, you can specify a fade transition to use. For example:

-- go to title "room", using iris fade
change_room(rm_title, 1) 

Scripting Functions

start_script(func, bg)

Creates new "thread" for script and adds it to list of local (or background) scripts.

Parameters

• func(function) - The function/script to run.
• bg(boolean, OPTIONAL - default = false) - If true, runs the script at a background/global-level (which always run), rather than room-level (which stop on exiting the current room). For example:

-- animate clock (as background script)
start_script(me.scripts.anim_clock, true)

script_running(func)

Returns whether or not the specified function is currently active, regardless of whether it's running at room-level or background-level.

stop_script(func)

Finds and terminates the specified function (if running)