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
respond "Active threads: #{stats[:active]}"

Constant Summary collapse

DEFAULT_SETTINGS =

Default settings for combat tracking

{
  enabled: false,           # Disabled by default, user must enable
  track_damage: true,
  track_wounds: true,
  track_statuses: true,
  track_ucs: true,          # Track UCS (position, tierup, smite)
  max_threads: 2,           # Keep threading for performance
  debug: false,
  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
COMBAT_RELEVANT_PATTERN =

Single compiled filter for combat-relevant content. One regex scan replaces ~11 include? calls plus a regex per line; alternation of literals compiles to an efficient multi-substring search.

Regexp.union(
  'points of damage',
  '<pushBold/>',              # Creatures
  '**',                       # Flares
  'AS:',                      # Attack rolls
  'swing', 'thrust', 'cast', 'gesture',
  'positioning against',      # UCS position
  'vulnerable to a followup', # UCS tierup
  'crimson mist'              # UCS smite
).freeze
COMBAT_RESOLUTION_PATTERN =

Regex pattern matching combat resolution outcomes: hit, miss, parry, block, dodge.

Case-insensitive word-boundary match used to identify combat resolution lines in game output.

Examples:

A matching line from game output

"You hit the ogre!" or "The troll parries your attack."

See Also:

/\b(?:hit|miss|parr|block|dodge)\b/i.freeze

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.buffer ⇒ Object (readonly)

Returns the value of attribute buffer.



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

def buffer
  @buffer
end

.settings ⇒ Object (readonly)

Returns the value of attribute settings.



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

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



215
216
217
 
# File 'documented/gemstone/combat/tracker.rb', line 215

def combat_relevant?(line)
  COMBAT_RELEVANT_PATTERN.match?(line) || COMBAT_RESOLUTION_PATTERN.match?(line)
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



233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
 
# File 'documented/gemstone/combat/tracker.rb', line 233

def configure(new_settings = {})
  initialize! unless @initialized
  @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

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

.debug? ⇒ Boolean

Check if debug mode is enabled

Returns:

  • (Boolean) —

    true if debug logging is active



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

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.



105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'documented/gemstone/combat/tracker.rb', line 105

def disable!
  return unless @enabled

  initialize! unless @initialized
  @enabled = false
  @settings[:enabled] = false
  save_settings # Persist disabled state
  remove_downstream_hook
  shutdown_processor

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

.disable_debug! ⇒ void

This method returns an undefined value.

Disable debug logging



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

def disable_debug!
  configure(debug: false)
  respond "[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 DB.



87
88
89
90
91
92
93
94
95
96
97
98
 
# File 'documented/gemstone/combat/tracker.rb', line 87

def enable!
  return if @enabled

  initialize! unless @initialized
  @enabled = true
  @settings[:enabled] = true # Force enabled in settings
  save_settings # Persist enabled state
  initialize_processor
  add_downstream_hook

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

.enable_debug! ⇒ void

This method returns an undefined value.

Enable debug logging



128
129
130
131
 
# File 'documented/gemstone/combat/tracker.rb', line 128

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

.enabled? ⇒ Boolean

Check if combat tracking is enabled

Lazily initializes on first check if not already initialized.

Returns:

  • (Boolean) —

    true if tracking is active



71
72
73
74
75
76
77
78
79
 
# File 'documented/gemstone/combat/tracker.rb', line 71

def enabled?
  # Before login data is available we can't load per-character
  # settings; report disabled instead of sleeping on the caller's
  # thread (the background init thread completes setup once ready).
  return false unless @initialized || xmldata_ready?

  initialize! unless @initialized
  @enabled && @settings[:enabled]
end

.fallback_hp ⇒ Integer

Retrieves the fallback maximum HP value used for creatures without template data.

Returns:

  • (Integer) —

    the configured fallback max HP (default 350)



153
154
155
156
 
# File 'documented/gemstone/combat/tracker.rb', line 153

def fallback_hp
  initialize! unless @initialized
  @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



165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
 
# File 'documented/gemstone/combat/tracker.rb', line 165

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 @async_processor
    @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



145
146
147
148
 
# File 'documented/gemstone/combat/tracker.rb', line 145

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

.stats ⇒ Hash

Get processing statistics

Returns:

  • (Hash) —

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



252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
 
# File 'documented/gemstone/combat/tracker.rb', line 252

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