Module: Lich::Gemstone::Combat::Tracker

Defined in:
documented/gemstone/combat/tracker.rb

Overview

Combat tracking system

Main interface for the combat tracking system. Integrates with Lich’s downstream hooks to process game output and track combat events.

Features:

  • Damage tracking and HP estimation

  • Wound/injury tracking by body part

  • Status effect tracking with auto-expiration

  • UCS (Unarmed Combat System) support

  • Async processing for performance

  • Automatic creature registry cleanup

Examples:

Enable tracking

Combat::Tracker.enable!
Combat::Tracker.configure(track_wounds: true, track_statuses: true)

Get statistics

stats = Combat::Tracker.stats
puts "Active threads: #{stats[:active]}"

Constant Summary collapse

DEFAULT_SETTINGS =

Default settings for combat tracking

{
  enabled: true,            # Enable by default for testing
  track_damage: true,
  track_wounds: true,
  track_statuses: true,     # Enable for testing
  track_ucs: true,          # Track UCS (position, tierup, smite)
  max_threads: 2,           # Keep threading for performance
  debug: false,             # Enable debug for testing
  buffer_size: 200,         # Increase for large combat chunks
  fallback_max_hp: 350,     # Default max HP when template unavailable
  cleanup_interval: 100,    # Cleanup creature registry every N chunks
  cleanup_max_age: 600      # Remove creatures older than N seconds (10 minutes)
}.freeze

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.buffer ⇒ Object (readonly)

Returns the value of attribute buffer.



59
60
61
 
# File 'documented/gemstone/combat/tracker.rb', line 59

def buffer
  @buffer
end

.settings ⇒ Object (readonly)

Returns the value of attribute settings.



59
60
61
 
# File 'documented/gemstone/combat/tracker.rb', line 59

def settings
  @settings
end

Class Method Details

.combat_relevant?(line) ⇒ Boolean

Check if line contains combat-relevant content

Quick filter to avoid processing non-combat lines.

Parameters:

  • line (String) —

    Game line to check

Returns:

  • (Boolean) —

    true if line may contain combat events



174
175
176
177
178
179
180
181
182
183
184
185
186
187
 
# File 'documented/gemstone/combat/tracker.rb', line 174

def combat_relevant?(line)
  line.include?('swing') ||
    line.include?('thrust') ||
    line.include?('cast') ||
    line.include?('gesture') ||
    line.include?('points of damage') ||
    line.include?('**') || # Flares
    line.include?('<pushBold/>') || # Creatures
    line.include?('AS:') || # Attack rolls
    line.include?('positioning against') || # UCS position
    line.include?('vulnerable to a followup') || # UCS tierup
    line.include?('crimson mist') || # UCS smite
    line.match?(/\b(?:hit|miss|parr|block|dodge)\b/i)
end

.configure(new_settings = {}) ⇒ void

This method returns an undefined value.

Update tracker settings

Merges new settings with existing ones and persists to Lich settings. Reinitializes processor if thread count changes.

Parameters:

  • new_settings (Hash) (defaults to: {}) —

    Settings to update

Options Hash (new_settings):

  • :enabled (Boolean) —

    Enable/disable tracking

  • :track_damage (Boolean) —

    Track damage

  • :track_wounds (Boolean) —

    Track wounds/injuries

  • :track_statuses (Boolean) —

    Track status effects

  • :track_ucs (Boolean) —

    Track UCS data

  • :max_threads (Integer) —

    Thread pool size

  • :debug (Boolean) —

    Enable debug logging



203
204
205
206
207
208
209
210
211
212
213
214
215
216
 
# File 'documented/gemstone/combat/tracker.rb', line 203

def configure(new_settings = {})
  @settings.merge!(new_settings)

  # Save to Lich settings system for persistence
  save_settings

  # Reinitialize processor if thread count changed
  if new_settings.key?(:max_threads)
    shutdown_processor
    initialize_processor
  end

  puts "[Combat] Settings updated: #{@settings}" if debug?
end

.debug? ⇒ Boolean

Check if debug mode is enabled

Returns:

  • (Boolean) —

    true if debug logging is active



107
108
109
 
# File 'documented/gemstone/combat/tracker.rb', line 107

def debug?
  @settings[:debug] || $combat_debug
end

.disable! ⇒ void

This method returns an undefined value.

Disable combat tracking

Shuts down the processor, removes hooks, and persists disabled state.



92
93
94
95
96
97
98
99
100
101
102
 
# File 'documented/gemstone/combat/tracker.rb', line 92

def disable!
  return unless @enabled

  @enabled = false
  @settings[:enabled] = false
  save_settings # Persist disabled state
  remove_downstream_hook
  shutdown_processor

  puts "[Combat] Combat tracking disabled" if debug?
end

.disable_debug! ⇒ void

This method returns an undefined value.

Disable debug logging



122
123
124
125
 
# File 'documented/gemstone/combat/tracker.rb', line 122

def disable_debug!
  configure(debug: false)
  puts "[Combat] Debug mode disabled"
end

.enable! ⇒ void

This method returns an undefined value.

Enable combat tracking

Initializes the processor, loads settings, and adds downstream hook. Persists enabled state to Lich settings.



74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'documented/gemstone/combat/tracker.rb', line 74

def enable!
  return if @enabled

  @enabled = true
  load_settings
  @settings[:enabled] = true # Force enabled in settings
  save_settings # Persist enabled state
  initialize_processor
  add_downstream_hook

  puts "[Combat] Combat tracking enabled" if debug?
end

.enable_debug! ⇒ void

This method returns an undefined value.

Enable debug logging



114
115
116
117
 
# File 'documented/gemstone/combat/tracker.rb', line 114

def enable_debug!
  configure(debug: true, enabled: true)
  puts "[Combat] Debug mode enabled"
end

.enabled? ⇒ Boolean

Check if combat tracking is enabled

Returns:

  • (Boolean) —

    true if tracking is active



64
65
66
 
# File 'documented/gemstone/combat/tracker.rb', line 64

def enabled?
  @enabled && @settings[:enabled]
end

.fallback_hp ⇒ Object 



136
137
138
 
# File 'documented/gemstone/combat/tracker.rb', line 136

def fallback_hp
  @settings[:fallback_max_hp]
end

.process(chunk) ⇒ void

This method returns an undefined value.

Process a chunk of game lines

Filters for combat-relevant lines and processes them. Triggers periodic cleanup of old creature instances.

Parameters:

  • chunk (Array<String>) —

    Game lines to process



147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
 
# File 'documented/gemstone/combat/tracker.rb', line 147

def process(chunk)
  return unless enabled?
  return if chunk.empty?

  # Quick filter - only process if combat-related content present
  return unless chunk.any? { |line| combat_relevant?(line) }

  if @settings[:max_threads] > 1
    @async_processor.process_async(chunk)
  else
    Processor.process(chunk)
  end

  # Periodic cleanup of old creature instances
  @chunks_processed += 1
  if @chunks_processed >= @settings[:cleanup_interval]
    cleanup_creatures
    @chunks_processed = 0
  end
end

.set_fallback_hp(hp_value) ⇒ void

This method returns an undefined value.

Set fallback HP value for creatures without templates

Parameters:

  • hp_value (Integer) —

    Default max HP value



131
132
133
134
 
# File 'documented/gemstone/combat/tracker.rb', line 131

def set_fallback_hp(hp_value)
  configure(fallback_max_hp: hp_value.to_i)
  puts "[Combat] Fallback max HP set to #{hp_value}"
end

.stats ⇒ Hash

Get processing statistics

Returns:

  • (Hash) —

    Stats including :enabled, :buffer_size, :settings, :active, :total



221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
 
# File 'documented/gemstone/combat/tracker.rb', line 221

def stats
  return { enabled: false } unless enabled?

  base_stats = {
    enabled: true,
    buffer_size: @buffer.size,
    settings: @settings
  }

  if @async_processor
    base_stats.merge(@async_processor.stats)
  else
    base_stats.merge(active: 0, total: 0)
  end
end