SCUMM 8 API: Functions

Below you will find the SCUMM-8 API reference. This API was heavily inspired by the original SCUMM command reference.

Basic Principles

• "Walkable" tiles For a sprite tile to be deemed "walkable", you must set the Flag 0 (see below). Otherwise the selected player will not be able to navigate a path to the tile when used in a room's map.

Definitions (Room/Object/Actor)

• map
  • The x1,y1 (top-left cell pos) and x2,y2 (bottom-right cell pos) of the map that should be used as the room.

For example: map = {80,24,103,31}

• name

  • The display name of an Object/Actor.

• x,y

  • Position of Object within a Room.

• w,h

  • Width and height (in sprite cel's) of an Object.

• state

  • The name of the state (which in turn, references a sprite number) to show for the object/actor. e.g. state=state_here

• trans_col

  • The color to draw as transparent (defaults to 0 = black)

• classes

  • Object and Actors can have multiple classes attributed, all of which have different effects. The available classes are:
    • class_untouchable = Item cannot be interacted with at all
    • class_pickupable = Item can be picked-up into actor's inventory
    • class_talkable = Actor can be talked to
    • class_giveable = Object can be given to another Actor
    • class_openable = Object can be opened
    • class_actor = Object is an Actor (not just a normal Object)
    • class_door = Object is a door (will allow easy linking to other rooms using target_door property.

For example: classes = { class_openable, class_door }

• flip_x

  • If true, the Object' sprite will be drawn flipped on the horizontal axis.

• use_pos

  • States the position the selected player will walk to when object is interacted with. The available use positions are:
    • pos_infront = Stand in-front of object
    • pos_left = Stand to the left of object
    • pos_right = Stand to the right of object
    • pos_above = Stand just above the object
    • pos_center = Stand in center of object

For example: use_pos = pos_left

• use_dir
  • States the direction the selected player will face to when object is interacted with. The available use positions are:
    • face_front
    • face_left
    • face_back
    • face_right

For example: use_dir = face_right

• repeat_x

  • Number of times to repeatedly draw object on the x axis (useful for tiled objects, such as fences)

• use_with

  • If specified, then the object can be used in combination with another object. For example: use_with=true

• col_replace

  • Allows you to specify an alternative color to one originally in room/object/actor sprites. Useful for reusing existing content. For example: col_replace = {5,2}

• lighting

  • Specifies the lighting level to use for a given room/object/actor, from 1=Normal to 0=black (default = 1).

TODO: Finish this...!

Functions

startup_script()

The script to be run on game start-up. Do all of your game initialisation here. For example, set the starting room, if nothing else.

camera_at(val)

Position the camera centrally at the following x pos.

camera_follow(actor)

Set the camera to follow the specified actor. e.g. 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). e.g. 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. There are three types of cutscenes:

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
)

dialog_clear()

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

dialog_set(msg_table)

-- 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).

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.

do_anim(actor, cmd_type, cmd_value)

Perform an Actor animation cycle. Currently, only one command is supported: "anim_face", which will animate the Actor to turn and face a specified target direction. For example: do_anim(selected_actor, "anim_face", "face_front")

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!

come_out_door(from_door, to_door, fade_effect)

This command is used to: change rooms, place the selected-actor at the door in a new room and also (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)

fades(fade, dir)

1=down, -1=up TODO: Document this...

change_room(new_room, fade)

TODO: Document this...

pickup_obj(objname)

TODO: Document this...

start_script(func, bg, noun1, noun2)

create new thread for script and add to list of local_scripts (or background scripts) TODO: Document this...

script_running(func)

TODO: Document this...

stop_script(func)

find script and stop it running TODO: Document this...

break_time(jiffies)

wait for cycles specified (min 1 cycle) TODO: Document this...

wait_for_message()

TODO: Document this...

say_line(actor, msg, use_caps, dont_wait_msg)

TODO: Document this...

stop_talking()

stop everyone talking & remove displayed text TODO: Document this...

print_line(msg, x, y, col, align, use_caps, dont_wait_msg)

punctuation...

":" new line, shown after text prior expires ";" new line, shown immediately note: an actor's talk animation is not activated as it is with say-line. TODO: Document this...

put_at(obj_or_actor, x, y, room)

TODO: Document this...

walk_to(actor, x, y)

walk actor to position TODO: Document this...

wait_for_actor(actor)

TODO: Document this...

proximity(obj1, obj2)

TODO: Document this...

valid_verb(verb, object)

TODO: Document this...

shake(enabled)

TODO: Document this...