SCUMM 8 API: Objects

Objects define stuff that the player can (typically) interact with inside the room - such as a fireplace or a door.

Object Definitions

Properties

The following properties apply to Object definitions.

• name

  • The display name of an Object/Actor.

• x,y

  • Position of Object within a Room.

• z

  • The z/depth pos of Object within a Room (useful for forcing objects to appear in-front/behind others)
  • The z-plane system in SCUMM-8 is from -64 to 64
    • (with the map being drawn at plane 0)
  • (Defaults to same as y pos)

• 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

• 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 = Object 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

• use_with

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

• dependent_on / dependent_on_state

  • Makes this object's state dependent on a particular state of another object. For example, a can of Pepsi inside a refrigerator. If the door is closed, the Pepsi would not be visible or touchable. The Pepsi is dependent on the refrigerator door being open.

    Code example:

    dependent_on = obj_fridge_door,
    dependent_on_state = "state_open",

• repeat_x

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

• trans_col

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

• 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).
  • For example: lighting = 0.75

• scale

  • Specifies the scale factor to use when drawing the object. Range is from 1 = 100% to 0=almost 0% (default = 1)

Verbs (func list)

The verbs property allows you to specify a list of functions for each verb that the object supports. When a user chooses a verb from the UI and clicks on the object, the defined function will be executed.

For example:

verbs = {
  walkto = function(me)
    come_out_door(me, obj_front_door)
  end,
  open = function(me)
    open_door(me, obj_front_door)
  end,
  close = function(me)
    close_door(me, obj_front_door)
  end
}

Scripts (list)

Allows you to specify a list of functions that are specific to a given object, actor or room. These scripts can then either be called directly (synchronously) or run asynchronously via the start_script() function.

For example:

scripts = {
  anim_fire = function()
    while true do
      for f=1,3 do
        obj_fire.state = f
        break_time(8)
      end
    end
  end
}

Init (func)

(OPTIONAL)
If specified, the init() function will be called on start-up, and allows for further object initialisation to be performed.

For example:

init = function(me)  
  me.target_door = obj_hall_door_library
end

Draw (func)

(OPTIONAL)
If specified, the draw() function will be called during the draw process, overriding any specified state property(s). This is useful if an object is dynamic or difficult to achieve with sprites alone. Such as circles, lines, particles, etc.

For example:

draw = function(me)
  -- switch transparency
  set_trans_col(8, true)
  -- draw stairs (using pico-8 standard map function)
  map(56,23, 68,52, 6,1)
end,