Changelog

Version: 0.1.9
Date: 2025-12-09
  Bugfixes:
    - Fixed show_player_inventory triggering god mode / infinite crafting
      - Accessing player.get_inventory(defines.inventory.god_main) had unintended side effects
      - Now only accesses god_main inventory when player.controller_type is actually god mode
      - Fixes issue where opening GUIs with show_player_inventory = true enabled cheat mode

Version: 0.1.8
Date: 2025-12-01
  Features:
    - Keep Vanilla GUI Option
      - New keep_vanilla_gui registration option (default: false)
      - When true, the vanilla entity GUI remains open instead of being replaced
      - Custom GUI frame appears alongside the vanilla GUI
      - Allows mods to extend/augment vanilla GUIs rather than fully replacing them
  Example:
    - remote.call("entity_gui_lib", "register", {
        mod_name = "my_mod",
        entity_name = "my-entity",
        keep_vanilla_gui = true,
        on_build = "build_my_gui",
      })

Version: 0.1.7
Date: 2025-11-30
  Features:
    - Transfer Restriction Option for create_inventory_display
      - New allow_player_transfer option (default: true)
      - When false, prevents items from being transferred to player inventory
      - Blocks shift-click from entity inventory to player inventory
      - Blocks placing cursor items (from restricted inventory) into player inventory
      - Still allows rearranging/swapping items within the entity inventory
      - Useful for mods that need view + internal manipulation without external transfers
  Technical:
    - Added storage.cursor_source for tracking transfer restrictions
  Example:
    - remote.call("entity_gui_lib", "create_inventory_display", container, {
        inventory = entity_inventory,
        interactive = true,
        allow_player_transfer = false,
      })

Version: 0.1.6
Date: 2025-11-30
  Features:
    - Factorio 2.0 Quality Support
      - Quality items now display with visual quality badge overlay in bottom-left corner
      - Quality-aware tooltips show item name with quality icon and tier name
      - Item transfers preserve quality (click, shift-click, swap operations)
      - Only stacks items with matching quality levels
      - Callbacks now receive quality in item_stack: {name, count, quality}
  Affected Areas:
    - Player inventory panel (show_player_inventory = true)
    - Entity inventories via create_inventory_display
    - All item transfer operations
  Technical:
    - Added build_item_tooltip() helper for quality-aware tooltips
    - Updated compute_inventory_hash() to detect quality changes
    - Updated update_slot_visual() to manage quality badge overlays
    - All set_stack() calls now include quality parameter
  Notes:
    - Quality field is nil for normal quality items
    - Quality name matches Factorio prototype names: "uncommon", "rare", "epic", "legendary"
    - Existing mods using this library get quality support automatically
    - Mods can optionally read item_stack.quality in callbacks for quality-specific logic

Version: 0.1.5
Date: 2025-11-27
  Features:
    - Added create_columns helper for multi-column layouts
      - Arranges content side-by-side in vertical columns
      - column_count: Number of columns (default 2)
      - spacing: Horizontal gap between columns in pixels (default 12)
      - widths: Optional array of fixed widths per column
      - vertical_spacing: Vertical gap within columns (default 8)
    - Enables more space-efficient GUI designs (e.g., cargo and fluid transfer side-by-side)

Version: 0.1.4
Date: 2025-11-26
  Features:
    - Player inventory position option via player_inventory_position registration setting
      - "right" (default) - Player inventory on right, custom content on left (existing behavior)
      - "left" - Player inventory on left, custom content on right (vanilla Factorio style)
    - Allows mods to match vanilla Factorio's machine GUI layout where inventory appears on the left

Version: 0.1.3
Date: 2025-11-25
  Features:
    - GUI Event Listener System for cross-mod integration
      - add_listener(config) - Register callbacks for entity GUI open/close events
      - remove_listener(entity_name_or_type, mod_name) - Unregister a listener
      - get_listeners(entity_name_or_type) - Query registered listeners
    - Listeners can observe GUIs from other mods without modifying them
    - Support for both entity_name and entity_type filtering
    - Listener callbacks receive: content frame, entity, player, registering mod name
  Use Cases:
    - Cross-mod integration (Mod B reacts when Mod A's GUI opens)
    - Overlay/addon mods that enhance other mods' GUIs
    - Logging/analytics mods
    - Adding tooltips or indicators to third-party entity GUIs
  Bugfixes:
    - Fixed shift-click transfers from player inventory not updating custom GUI elements
      - Previously, shift-clicking from player → entity would not trigger callbacks to update UI (e.g., "Have" columns)
      - Now calls target inventory's on_transfer callback with transfer_type = "quick_transfer_received"
      - Falls back to full GUI refresh if no on_transfer callback is configured
  Internal:
    - Added storage.listeners for tracking listener registrations
    - Listeners called after registering mod's on_build/on_close callbacks
    - pcall protection prevents listener errors from breaking core functionality

Version: 0.1.2
Date: 2025-11-25
  Features:
    - Interactive inventory support for create_inventory_display
      - interactive (boolean) - Enable click-to-transfer items with player cursor
      - read_only (boolean) - Disable transfers even if interactive is true
      - item_filter (table) - Optional whitelist of allowed items
      - on_transfer (string) - Remote callback triggered after item transfers
    - Player inventory panel via show_player_inventory registration option
      - Displays scrollable player inventory alongside custom entity GUIs
      - Fully interactive - click to pick up/place items
      - Works in both normal mode and editor/god mode
    - Shift-click quick transfer between inventories
      - From player inventory to entity inventory and vice versa
      - Stacks with existing items first, then uses empty slots
    - New remote function: refresh_inventory_display(inv_table, inventory)
      - Manually refresh inventory slot visuals without rebuilding GUI
  Interaction Behaviors:
    - Left-click empty slot with cursor item: Insert all items
    - Left-click filled slot with same item: Stack items (respects stack size)
    - Left-click filled slot with different item: Swap items
    - Left-click filled slot with empty cursor: Take all items
    - Right-click filled slot with empty cursor: Take half stack
    - Shift + left-click filled slot: Quick transfer to other inventory
  Bugfixes:
    - Fixed tab selection being reset during periodic refresh
    - Fixed function definition order issue with get_helper_callbacks
    - Fixed GUI element hierarchy navigation after adding main_flow wrapper
    - Fixed editor/god mode inventory support
    - Fixed numeric inventory ID type checking errors
    - Fixed sprite/tooltip clearing using empty string instead of nil
  Optimizations:
    - Cache UI element references in gui_data (eliminates GUI hierarchy traversal in on_tick)
    - Inventory hash check to skip refresh when contents unchanged
    - Direct inventory table references (eliminates recursive DOM traversal)
    - Early exit in all event handlers using fast prefix check
    - Cache color picker element references (eliminates DOM traversal on slider changes)
    - Static status lookup table built once at module level
    - Debounced item/recipe search (6 tick delay for smoother typing)
  Internal:
    - Added storage.inventory_refs for tracking interactive inventory references
    - Added storage.inventory_tables for direct table element access
    - Added storage.pending_searches for debounced search queue
    - Added INTERACTION_COOLDOWN (30 ticks) to prevent visual glitches during rapid clicking
    - Tab selection preservation during all refresh operations

Version: 0.1.1
Date: 2025-11-25
  Features:
    - Added create_slider helper - Labeled slider with automatic value display
      - Returns flow and slider elements
      - Auto-updates value label on change
      - Callback: function(player, value, data)
    - Added create_number_input helper - Text field with +/- buttons
      - Numeric validation and clamping
      - Configurable min/max/step
      - Callback: function(player, value, data)
    - Added create_dropdown helper - Dropdown with callback handling
      - Optional value mapping (items → values)
      - Callback: function(player, selected_index, selected_value, data)
    - Added create_toggle_group helper - Grouped checkboxes/radiobuttons
      - mutual_exclusion = true for radio button behavior
      - Callback: function(player, state, value, data)
    - Added create_inventory_display helper - Show entity inventories with slot buttons
      - Configurable columns and empty slot visibility
      - Callback: function(player, slot_index, item_stack, data)
    - Added create_recipe_selector helper - Searchable recipe picker
      - Prototype filtering support
      - Real-time search filtering
      - Callback: function(player, recipe_name, data)
    - Added create_item_selector helper - Searchable item picker
      - Prototype filtering support
      - Real-time search filtering
      - Callback: function(player, item_name, data)
    - Added create_elem_button helper - Simple choose-elem-button wrapper
      - Supports item, recipe, signal, fluid, entity types
      - Callback: function(player, elem_value, data)
    - Added create_signal_selector helper - Circuit network signal picker
      - Uses Factorio's built-in signal selector
      - Callback: function(player, signal_id, data)
    - Added create_color_picker helper - RGB color selection with sliders
      - Optional alpha channel support
      - Live preview tooltip
      - Callback: function(player, color, data)
  Event Handlers:
    - on_gui_value_changed for sliders and color picker
    - on_gui_selection_state_changed for dropdowns
    - on_gui_checked_state_changed for toggles
    - on_gui_text_changed for number inputs and search fields
    - on_gui_elem_changed for element buttons and signal selectors
    - Click handling for +/- buttons, inventory slots, item/recipe selectors
  Storage:
    - Added storage.helper_callbacks for persisting callback data

Version: 0.1.0
Date: 2025-11-24
  Features:
    - Initial release of Entity GUI Library
    - Automatic interception and replacement of vanilla entity GUIs
    - Vanilla-styled frame with draggable titlebar and close button
    - Entity preview widget with configurable size (preview_size option)
    - Comprehensive entity status display (35+ status types)
    - E key closes GUI to match vanilla behavior
    - Remote interface API for mod registration
    - Support for both entity_name and entity_type registration
    - on_build callback for adding custom GUI content
    - on_close callback for cleanup when GUI closes
    - on_update callback with configurable update_interval for auto-refreshing GUIs
    - Priority system for handling conflicts between multiple mods
    - Tabbed interface helper (create_tabs)
    - Confirmation dialog helper (show_confirmation)
    - GUI refresh function to rebuild content without closing
    - Debug mode for logging registrations and GUI events
    - Locale support with translatable strings
    - Example mod demonstrating all features