Shields Library - Machine Reference

This page contains machine-readable reference information about the Lua shields library for automated tools and AI assistants.

• Entity Type: Lua Library
• File Path: scripts/lib/shields.lua
• Purpose: Factory functions for creating shield items with consistent mechanics
• Language: Lua

• Description: Creates a complete shield item configuration table
• Parameters:
  • `shieldLevel` (number): Shield level/tier (1-4 typically)
  • `shieldDesc` (string): String resource ID for shield description (e.g., “ToughShield_desc”)
  • `shieldBuff` (string, optional): Buff class name to apply (default: “ShieldLeft”)
• Returns: Shield configuration table with activate, info, typicalSTR, requiredSTR, slot, accuracyFactor, damageRoll, attackDelayFactor, attackProc, goodForMelee functions

• Description: Calculates damage blocked by shield
• Formula: blockForLevel[shieldLevel] * (1.3 ^ itemLevel)
• Parameters:
  • `shieldLevel` (number): Shield tier level
  • `itemLevel` (number): Item upgrade level

• Description: Calculates block chance percentage
• Formula: chanceForLevel[shieldLevel] * (1 - weightPenalty * 0.1)
• Weight Penalty: max(strForLevel[shieldLevel] - str, 0)

• Description: Calculates recharge time between blocks
• Formula: 5 + weightPenalty
• Weight Penalty: max(strForLevel[shieldLevel] - str, 0)

• Description: Additional wait time after blocking
• Formula: max(str - strForLevel[shieldLevel], 0)

• Description: Generates info text for shield in off-hand slot
• Template: ShieldInfoTemplate + ShieldStrTemplate from string resources

• Description: Generates info text for shield used as weapon (two-handed)
• Template: ShieldWeaponInfo from string resources

• strForLevel: Minimum STR required per shield level {11, 13, 15, 17, 19…}
• chanceForLevel: Base block chance per level {0.15, 0.20, 0.25, 0.30, 0.35…}
• blockForLevel: Base block amount per level {2, 3, 4, 5, 6…}

```lua local shields = require “scripts/lib/shields” local shieldLevel = 2 local shieldDesc = “ToughShield_desc” local baseDesc = shields.makeShield(shieldLevel, shieldDesc) baseDesc.desc = function(self, item)

  return {
      image = 1,
      imageFile = "items/shields.png",
      name = "ToughShield_name",
      info = shieldDesc,
      price = 40 * shieldLevel,
      equipable = "left_hand",
      upgradable = true
  }

end return item.init(baseDesc) ```

• Wooden Shield - Level 1
• Tough Shield - Level 2
• Strong Shield - Level 3
• Royal Shield - Level 4

• shields.lua - Library source
• shields.lua (stats) - Stat tables
• ToughShield.lua - Example usage

• ShieldInfoTemplate
• ShieldStrTemplate
• ShieldWeaponInfo
• [ShieldName]_Name (per shield)
• [ShieldName]_Desc (per shield)

• Shield Class - Java base class reference
• Shields - English wiki page
• Wooden Shield Item - Basic shield reference
• Tough Shield Item - Level 2 shield reference