Giftsurprise

Based on game build 714014 | Last updated: 2026-03-05

Overview

giftsurprise is a lightweight entity that acts as a wrapped-item placeholder for spawning creatures (e.g., hounds) when unpacked from a gift. It relies on the unwrappable and inventoryitem components to manage its lifecycle—remaining unpickupable while wrapped, and spawning/activating a creature upon unwrapping. It does not represent a playable item itself but serves as a runtime constructor for dynamic loot/spawn effects.

Usage example

-- Wrap a gift with a surprise hound and fillers
local gift = SpawnPrefab("gift")
gift.components.unwrappable:WrapItems({
    SpawnPrefab("giftsurprise"):SetCreatureSurprise("hound"),
    SpawnPrefab("giftsurprise"),
    SpawnPrefab("giftsurprise"),
    SpawnPrefab("giftsurprise"),
})

Dependencies & tags

Components used: inventoryitem
Tags: None identified.

Properties

Property	Type	Default Value	Description
creature	string or nil	nil	Prefab name of the creature to spawn on unwrap. Must be set via SetCreatureSurprise.

Main functions

SetCreatureSurprise(prefab)

• Description: Configures the creature prefab to spawn upon unwrapping. Attaches event handlers for wrappeditem and unwrappeditem and disables automatic pickup.
• Parameters: prefab (string) — The name of the prefab to spawn (e.g., "hound").
• Returns: inst — The entity instance, allowing method chaining.
• Error states: Does nothing if prefab is nil; no validation is performed.

Events & listeners

• Listens to:
  • wrappeditem — Triggers visual jiggle on the gift container.
  • unwrappeditem — Spawns the configured creature, plays its surprise_spawn state (if available), and suggests it as a combat target to the unwrapping actor (if combat-capable).
• Pushes: None directly.