LockDoors API - Hytale Extension

LockDoors API is a powerful extension for Hytale that provides a complete system of customizable block interactions. Design doors, secret passages, treasure chests, and other interactive elements that require specific items to activate. Perfect for adventure maps, dungeons, escape rooms, and narrative-driven experiences.

✨ Features

🔑 Advanced Lock System

Customizable key requirements: Configure which item unlocks each door
Auto-relock capability: Doors automatically lock after a configurable time period
Multi-state transitions: Support for complex animation sequences (locked → opening → open → closing → locked)
Smart cooldown system: Prevents spam and item duplication exploits

⏱️ Flexible Timing Controls

Unlock delay: Configure how long before the door opens
Relock timer: Set how long the door stays unlocked
Animation duration: Control closing animation length
Independent timing: Each phase can have different timing

📝 Rich Notification System

4 message types: Success, already unlocked, relocking, and error messages
Fully customizable text: Configure main titles and subtitles for each message
Visual customization: Choose major/minor title styling and optional icons
Adjustable duration: Control display time for each message independently

🔄 Technical Excellence

Rotation preservation: Doors maintain their orientation through all state changes
Anti-duplication: Robust system prevents item exploitation during delays
Thread-safe scheduling: Reliable timed events using Hytale's scheduler
Null-safe design: Comprehensive error handling prevents crashes

🎨 No-Code Configuration

Configure everything visually from the Hytale Asset Editor
No programming knowledge required
Template-based workflow for quick setup
Full control over behavior and appearance

🎮 How to Create a Custom Locked Door

1. Create Your Mod Package

Open the Hytale Asset Editor
Create a new asset package or open an existing one
Name it descriptively (e.g., "DungeonDoors" or "SecretPassages")

2. Use the Door Template

Locate the Template_Door asset in the Asset Editor
Right-click and select Duplicate to create your own door variant
Rename it to something meaningful (e.g., "Ancient_Locked_Door")

3. Customize the Visual Model

Navigate to Block Type > Rendering and configure:

CustomModel: Select your .blockymodel file
CustomModelTexture: Assign textures to your model
HitboxType: Choose appropriate collision (e.g., Door, Door_Medium, Door_Large)

💡 Tip: Create separate models for locked, opening, open, and closing states for smooth animations.

4. Configure the Unlock Interaction

Navigate to: Block Type > Interactions > Use > Interactions > 0

Basic Configuration

Field	Description	Example	Type
Type	Interaction class (don't change)	`UnlockInteraction`	String
RequiredItem	Item ID that unlocks this door	`Ingredient_Charcoal`	String
UnlockDelaySeconds	Seconds before door opens	`2`	Integer
OpenStateName	Block state when unlocked	`OpenDoorIn`	String

Success Messages

Field	Description	Example
SuccessTitleMain	Main title on unlock	`"Ancient Door Unlocked!"`
SuccessTitleSecondary	Subtitle on unlock	`"The passage reveals itself"`

Error Messages

Field	Description	Example
ErrorTitleMain	Main title for wrong item	`"Wrong Key!"`
ErrorTitleSecondary	Subtitle for wrong item	`"This key doesn't fit"`

Auto-Relock Settings (Optional)

Field	Description	Example	Default
AutoRelock	Enable automatic relocking	`true`	`false`
RelockDelaySeconds	Seconds before door closes	`10`	`10`
CloseStateName	Block state for closing animation	`CloseDoorIn`	`"CloseDoorIn"`
BlockedStateName	Block state when locked	`DoorBlocked`	`"DoorBlocked"`
CloseAnimationSeconds	Duration of closing animation	`1`	`1`

Relock Messages (Optional)

Field	Description	Example
RelockTitleMain	Main title when relocking	`"Door Sealing!"`
RelockTitleSecondary	Subtitle when relocking	`"The passage closes"`

Already Unlocked Messages (Optional)

Field	Description	Example
AlreadyUnlockedTitleMain	Main title when already open	`"Already Open!"`
AlreadyUnlockedTitleSecondary	Subtitle when already open	`"The door is unlocked"`

Visual Settings

Field	Description	Example	Default
IsMajorTitle	Show as prominent title	`true`	`true`
TitleIcon	Optional icon identifier	`"icon_key"`	`null`

5. Important Block Flags

⚠️ Critical Settings - Navigate to Block Type > Flags:

✅ IsUsable: Must be set to true (enables player interaction)
✅ Verify all state block IDs exist in your assets

📋 Configuration Examples

Example 1: Simple Locked Door

A basic door that unlocks permanently:

json

{
  "Type": "UnlockInteraction",
  "RequiredItem": "Item_GoldenKey",
  "UnlockDelaySeconds": 1,
  "OpenStateName": "DoorOpen",
  "SuccessTitleMain": "Door Unlocked!",
  "SuccessTitleSecondary": "The way is open",
  "ErrorTitleMain": "Locked!",
  "ErrorTitleSecondary": "You need a golden key",
  "AutoRelock": false
}

Example 2: Timed Security Door

A door that locks itself after 10 seconds:

json

{
  "Type": "UnlockInteraction",
  "RequiredItem": "Item_SecurityCard",
  "UnlockDelaySeconds": 2,
  "OpenStateName": "SecurityDoorOpen",
  "AutoRelock": true,
  "RelockDelaySeconds": 10,
  "CloseStateName": "SecurityDoorClosing",
  "BlockedStateName": "SecurityDoorLocked",
  "CloseAnimationSeconds": 2,
  "SuccessTitleMain": "Access Granted",
  "SuccessTitleSecondary": "Security door unlocking...",
  "RelockTitleMain": "Security Alert",
  "RelockTitleSecondary": "Door is locking!",
  "AlreadyUnlockedTitleMain": "Door Active",
  "AlreadyUnlockedTitleSecondary": "Security door is already open"
}

Example 3: Puzzle Secret Passage

A hidden door with thematic messages:

json

{
  "Type": "UnlockInteraction",
  "RequiredItem": "Item_AncientMedallion",
  "UnlockDelaySeconds": 3,
  "OpenStateName": "SecretWallOpen",
  "AutoRelock": true,
  "RelockDelaySeconds": 15,
  "CloseStateName": "SecretWallClosing",
  "BlockedStateName": "SecretWallSealed",
  "CloseAnimationSeconds": 3,
  "SuccessTitleMain": "Ancient Magic Awakens",
  "SuccessTitleSecondary": "The wall begins to shift...",
  "RelockTitleMain": "The Magic Fades",
  "RelockTitleSecondary": "The passage seals itself",
  "AlreadyUnlockedTitleMain": "Still Active",
  "AlreadyUnlockedTitleSecondary": "The magic lingers",
  "ErrorTitleMain": "Nothing Happens",
  "ErrorTitleSecondary": "This item holds no power here",
  "IsMajorTitle": true
}

🔧 Advanced Usage

State Lifecycle

Understanding the complete door state cycle:

DoorBlocked (Initial): Door is locked, player cannot pass
Player uses correct item: Item is consumed
UnlockDelaySeconds wait: Brief pause for unlock animation
OpenDoorIn: Door opens, player can pass through
RelockDelaySeconds wait (if AutoRelock enabled): Door stays open
CloseDoorIn: Closing animation plays
CloseAnimationSeconds wait: Animation completes
DoorBlocked: Door returns to locked state

Cooldown System

The cooldown prevents:

Item spam during unlock process
Multiple players consuming items simultaneously
Exploitation of timing delays

When AutoRelock is enabled, the cooldown lasts for:

Total Cooldown = UnlockDelaySeconds + RelockDelaySeconds + CloseAnimationSeconds

During this time, attempting to interact shows the "Already Unlocked" message.

Creating Custom Animations

For best results:

Create 4 different block models: Locked, Opening, Open, Closing
Set up 4 block states in your BlockType
Configure smooth transitions between states
Match UnlockDelaySeconds and CloseAnimationSeconds to your animation length

🐛 Troubleshooting

Door Doesn't Respond to Interaction

Solutions:

✅ Verify IsUsable: true is enabled in Block Type > Flags
✅ Check that you're using the exact item specified in RequiredItem
✅ Ensure the block has the interaction properly configured
✅ Test with the correct item in your hotbar

Item Consumed But Door Doesn't Open

Solutions:

✅ Verify OpenStateName matches an existing block state
✅ Check that the target block asset exists in your package
✅ Wait for UnlockDelaySeconds - the delay is intentional
✅ Check console for error messages

Title Messages Don't Appear

Solutions:

✅ Verify all message fields are properly filled
✅ Check that IsMajorTitle is set correctly
✅ Ensure message strings don't contain syntax errors
✅ Test with simplified messages first

Door Loses Rotation When Opening

Solutions:

🎉 This is handled automatically by the system
If rotation is lost, ensure all block states have proper rotation variants
Report persistent issues as a bug

Already Unlocked Message Shows Immediately

Solutions:

✅ This is expected behavior when AutoRelock is enabled
The door is in an active unlock cycle
Wait for the door to complete its full cycle
Reduce RelockDelaySeconds if the wait is too long

Door Doesn't Relock Automatically

Solutions:

✅ Verify AutoRelock: true is set
✅ Check that CloseStateName and BlockedStateName exist
✅ Ensure RelockDelaySeconds and CloseAnimationSeconds are set
✅ Verify no errors in console during the relock process