LockDoors API

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:

1. DoorBlocked (Initial): Door is locked, player cannot pass
2. Player uses correct item: Item is consumed
3. UnlockDelaySeconds wait: Brief pause for unlock animation
4. OpenDoorIn: Door opens, player can pass through
5. RelockDelaySeconds wait (if AutoRelock enabled): Door stays open
6. CloseDoorIn: Closing animation plays
7. CloseAnimationSeconds wait: Animation completes
8. 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:

1. Create 4 different block models: Locked, Opening, Open, Closing
2. Set up 4 block states in your BlockType
3. Configure smooth transitions between states
4. 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