Class: Lich::Gemstone::CreatureInstance

Inherits:
Object
  • Object
show all
Defined in:
documented/gemstone/creature.rb

Overview

Represents an instance of a creature in the game. This class manages the state and attributes of a creature during gameplay.

Examples:

Creating a new creature instance

creature = Lich::Gemstone::CreatureInstance.new(1, "Goblin", "Goblin")

Constant Summary collapse

BODY_PARTS = 
%w[abdomen back chest head leftArm leftEye leftFoot leftHand leftLeg neck nerves rightArm rightEye rightFoot rightHand rightLeg]
UCS_TTL =

UCS data expires after 2 minutes

120
UCS_SMITE_TTL =

Smite effect expires after 15 seconds

15
STATUS_DURATIONS =

Status effect durations (in seconds) for auto-cleanup nil = no auto-cleanup (waits for removal message)

{
  'breeze'      => 6, # 6 seconds roundtime
  'bind'        => 10, # 10 seconds typical
  'web'         => 8, # 8 seconds typical
  'entangle'    => 10, # 10 seconds typical
  'hypnotism'   => 12, # 12 seconds typical
  'calm'        => 15, # 15 seconds typical
  'mass_calm'   => 15, # 15 seconds typical
  'sleep'       => 8, # 8 seconds typical (can wake early)
  # Statuses with reliable removal messages - no duration needed
  'stunned'     => nil, # Has removal messages
  'immobilized' => nil, # Has removal messages
  'prone'       => nil,         # Has removal messages
  'blind'       => nil,         # Has removal messages
  'sunburst'    => nil, # Has removal messages
  'webbed'      => nil, # Has removal messages
  'poisoned'    => nil # Has removal messages
}.freeze
@@instances = 
{}
@@max_size = 
1000
@@auto_register = 
true

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(id, noun, name) ⇒ CreatureInstance

Returns a new instance of CreatureInstance.



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

def initialize(id, noun, name)
  @id = id.to_i
  @noun = noun
  @name = name
  @status = []
  @injuries = Hash.new(0)
  @health = nil
  @damage_taken = 0
  @created_at = Time.now
  @fatal_crit = false
  @status_timestamps = {}
  @ucs_position = nil
  @ucs_tierup = nil
  @ucs_smote = nil
  @ucs_updated = nil
end

Instance Attribute Details

#created_at ⇒ Object

Returns the value of attribute created_at.



190
191
192
 
# File 'documented/gemstone/creature.rb', line 190

def created_at
  @created_at
end

#damage_taken ⇒ Object

Returns the value of attribute damage_taken.



190
191
192
 
# File 'documented/gemstone/creature.rb', line 190

def damage_taken
  @damage_taken
end

#fatal_crit ⇒ Object

Returns the value of attribute fatal_crit.



190
191
192
 
# File 'documented/gemstone/creature.rb', line 190

def fatal_crit
  @fatal_crit
end

#health ⇒ Object

Returns the value of attribute health.



190
191
192
 
# File 'documented/gemstone/creature.rb', line 190

def health
  @health
end

#id ⇒ Object

Returns the value of attribute id.



190
191
192
 
# File 'documented/gemstone/creature.rb', line 190

def id
  @id
end

#injuries ⇒ Object

Returns the value of attribute injuries.



190
191
192
 
# File 'documented/gemstone/creature.rb', line 190

def injuries
  @injuries
end

#name ⇒ Object

Returns the value of attribute name.



190
191
192
 
# File 'documented/gemstone/creature.rb', line 190

def name
  @name
end

#noun ⇒ Object

Returns the value of attribute noun.



190
191
192
 
# File 'documented/gemstone/creature.rb', line 190

def noun
  @noun
end

#status ⇒ Object

Returns the value of attribute status.



190
191
192
 
# File 'documented/gemstone/creature.rb', line 190

def status
  @status
end

#status_timestamps ⇒ Object

Returns the value of attribute status_timestamps.



190
191
192
 
# File 'documented/gemstone/creature.rb', line 190

def status_timestamps
  @status_timestamps
end

#ucs_position ⇒ Integer?

Retrieves the UCS position for the creature instance.

Returns:

  • (Integer, nil) —

    The current UCS position, or nil if expired.



382
383
384
385
 
# File 'documented/gemstone/creature.rb', line 382

def ucs_position
  return nil if ucs_expired?
  @ucs_position
end

#ucs_smote ⇒ Object

Returns the value of attribute ucs_smote.



190
191
192
 
# File 'documented/gemstone/creature.rb', line 190

def ucs_smote
  @ucs_smote
end

#ucs_tierup ⇒ String?

Retrieves the UCS tier-up for the creature instance.

Returns:

  • (String, nil) —

    The current UCS tier-up, or nil if expired.



389
390
391
392
 
# File 'documented/gemstone/creature.rb', line 389

def ucs_tierup
  return nil if ucs_expired?
  @ucs_tierup
end

#ucs_updated ⇒ Object

Returns the value of attribute ucs_updated.



190
191
192
 
# File 'documented/gemstone/creature.rb', line 190

def ucs_updated
  @ucs_updated
end

Class Method Details

.[](id) ⇒ Object 



562
563
564
 
# File 'documented/gemstone/creature.rb', line 562

def [](id)
  @@instances[id.to_i]
end

.all ⇒ Array<CreatureInstance>

Returns all registered creature instances.

Returns:



568
569
570
 
# File 'documented/gemstone/creature.rb', line 568

def all
  @@instances.values
end

.auto_register? ⇒ Boolean

Returns:

  • (Boolean) 


524
525
526
 
# File 'documented/gemstone/creature.rb', line 524

def auto_register?
  @@auto_register
end

.cleanup_old(max_age_seconds = 600) ⇒ Object 



576
577
578
579
580
581
 
# File 'documented/gemstone/creature.rb', line 576

def cleanup_old(max_age_seconds = 600)
  cutoff = Time.now - max_age_seconds
  removed = @@instances.select { |_id, instance| instance.created_at < cutoff }.size
  @@instances.reject! { |_id, instance| instance.created_at < cutoff }
  removed
end

.clear ⇒ Object 



572
573
574
 
# File 'documented/gemstone/creature.rb', line 572

def clear
  @@instances.clear
end

.configure(max_size: 1000, auto_register: true) ⇒ Object 



519
520
521
522
 
# File 'documented/gemstone/creature.rb', line 519

def configure(max_size: 1000, auto_register: true)
  @@max_size = max_size
  @@auto_register = auto_register
end

.full? ⇒ Boolean

Returns:

  • (Boolean) 


532
533
534
 
# File 'documented/gemstone/creature.rb', line 532

def full?
  size >= @@max_size
end

.register(name, id, noun = nil) ⇒ CreatureInstance?

Registers a new creature instance with the specified name and ID.

Parameters:

  • name (String) —

    The name of the creature.

  • id (Integer) —

    The unique identifier for the creature instance.

  • noun (String, nil) (defaults to: nil) —

    The noun used to refer to the creature, defaults to nil.

Returns:

  • (CreatureInstance, nil) —

    The registered creature instance, or nil if registration failed.



541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
 
# File 'documented/gemstone/creature.rb', line 541

def register(name, id, noun = nil)
  return nil unless auto_register?
  return @@instances[id.to_i] if @@instances[id.to_i] # Already exists

  # Auto-cleanup old instances if registry is full - get progressively more aggressive
  if full?
    # Try 120 minutes, then 15 minute intervals.
    [7200, 6300, 5400, 4500, 3600, 2700, 1800, 900].each do |age_threshold|
      removed = cleanup_old(age_threshold)
      respond "--- Auto-cleanup: removed #{removed} old creatures (threshold: #{age_threshold}s)" if removed > 0 && $creature_debug
      break unless full?
    end
    return nil if full? # Still full after all cleanup attempts
  end

  instance = new(id, noun, name)
  @@instances[id.to_i] = instance
  respond "--- Creature registered: #{name} (#{id})" if $creature_debug
  instance
end

.size ⇒ Object 



528
529
530
 
# File 'documented/gemstone/creature.rb', line 528

def size
  @@instances.size
end

Instance Method Details

#add_damage(amount) ⇒ void

This method returns an undefined value.

Adds damage taken to the creature instance.

Parameters:

  • amount (Integer) —

    The amount of damage to add.



435
436
437
 
# File 'documented/gemstone/creature.rb', line 435

def add_damage(amount)
  @damage_taken += amount.to_i
end

#add_injury(body_part, amount = 1) ⇒ Object

Adds an injury to a specified body part of the creature instance.

Parameters:

  • body_part (String) —

    The body part to injure.

  • amount (Integer) (defaults to: 1) —

    The amount of injury to add, defaults to 1.

Raises:

  • (ArgumentError) —

    If the body part is invalid.



398
399
400
401
402
403
 
# File 'documented/gemstone/creature.rb', line 398

def add_injury(body_part, amount = 1)
  unless BODY_PARTS.include?(body_part.to_s)
    raise ArgumentError, "Invalid body part: #{body_part}"
  end
  @injuries[body_part.to_sym] += amount
end

#add_status(status, duration = nil) ⇒ void

This method returns an undefined value.

Adds a status effect to the creature instance.

Parameters:

  • status (String) —

    The status to add.

  • duration (Integer, nil) (defaults to: nil) —

    The duration of the status effect in seconds, or nil for no auto-expiry.



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

def add_status(status, duration = nil)
  return if @status.include?(status)

  @status << status

  # Set expiration timestamp for timed statuses
  status_key = status.to_s.downcase
  duration ||= STATUS_DURATIONS[status_key]
  if duration
    @status_timestamps[status] = Time.now + duration
    respond "  +status: #{status} (expires in #{duration}s)" if $creature_debug
  else
    respond "  +status: #{status} (no auto-expiry)" if $creature_debug
  end
end

#cleanup_expired_statuses ⇒ void

This method returns an undefined value.

Cleans up expired status effects from the creature instance.



280
281
282
283
284
285
286
287
288
289
 
# File 'documented/gemstone/creature.rb', line 280

def cleanup_expired_statuses
  return unless @status_timestamps && !@status_timestamps.empty?

  now = Time.now
  @status_timestamps.select { |_status, expires_at| expires_at <= now }.keys.each do |expired_status|
    @status.delete(expired_status)
    @status_timestamps.delete(expired_status)
    respond "  ~status: #{expired_status} (auto-expired)" if $creature_debug
  end
end

#clear_smote ⇒ void

This method returns an undefined value.

Clears the smote status from the creature instance.



367
368
369
370
371
 
# File 'documented/gemstone/creature.rb', line 367

def clear_smote
  @ucs_smote = nil
  @ucs_updated = Time.now
  respond "  UCS: smote cleared" if $creature_debug
end

#current_hp ⇒ Integer?

Retrieves the current hit points for the creature instance.

Returns:

  • (Integer, nil) —

    The current hit points, or nil if max_hp is not set.



463
464
465
466
 
# File 'documented/gemstone/creature.rb', line 463

def current_hp
  return nil unless max_hp
  [max_hp - @damage_taken, 0].max
end

#dead? ⇒ Boolean

Checks if the creature instance is dead (current HP is 0).

Returns:

  • (Boolean) —

    True if dead, otherwise false.



485
486
487
 
# File 'documented/gemstone/creature.rb', line 485

def dead?
  current_hp == 0
end

#essential_data ⇒ Hash

Retrieves essential data for the creature instance.

Returns:

  • (Hash) —

    A hash containing essential attributes of the creature instance.



497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
 
# File 'documented/gemstone/creature.rb', line 497

def essential_data
  {
    id: @id,
    noun: @noun,
    name: @name,
    status: @status,
    injuries: @injuries,
    health: @health,
    damage_taken: @damage_taken,
    max_hp: max_hp,
    current_hp: current_hp,
    hp_percent: hp_percent,
    has_template: has_template?,
    created_at: @created_at,
    ucs_position: ucs_position,
    ucs_tierup: ucs_tierup,
    ucs_smote: smote?
  }
end

#fatal_crit? ⇒ Boolean

Checks if the creature instance has a fatal critical hit.

Returns:

  • (Boolean) —

    True if it has, otherwise false.



421
422
423
 
# File 'documented/gemstone/creature.rb', line 421

def fatal_crit?
  @fatal_crit
end

#has_status?(status) ⇒ Boolean

Checks if the creature instance has a specific status effect.

Parameters:

  • status (String) —

    The status to check.

Returns:

  • (Boolean) —

    True if the status is present, otherwise false.



294
295
296
297
 
# File 'documented/gemstone/creature.rb', line 294

def has_status?(status)
  cleanup_expired_statuses # Clean up expired statuses first
  @status.include?(status.to_s)
end

#has_template? ⇒ Boolean

Checks if the creature instance has an associated template.

Returns:

  • (Boolean) —

    True if the instance has a template, otherwise false.



245
246
247
 
# File 'documented/gemstone/creature.rb', line 245

def has_template?
  !template.nil?
end

#hp_percent ⇒ Float?

Calculates the percentage of current hit points relative to max hit points.

Returns:

  • (Float, nil) —

    The percentage of current hit points, or nil if max_hp is not set.



470
471
472
473
 
# File 'documented/gemstone/creature.rb', line 470

def hp_percent
  return nil unless max_hp && max_hp > 0
  ((current_hp.to_f / max_hp) * 100).round(1)
end

#injured?(location, threshold = 1) ⇒ Boolean

Checks if the creature instance is injured at a specified location.

Parameters:

  • location (String) —

    The body part to check for injury.

  • threshold (Integer) (defaults to: 1) —

    The injury threshold to check against, defaults to 1.

Returns:

  • (Boolean) —

    True if injured, otherwise false.



409
410
411
 
# File 'documented/gemstone/creature.rb', line 409

def injured?(location, threshold = 1)
  @injuries[location.to_sym] >= threshold
end

#injured_locations(threshold = 1) ⇒ Array<Symbol>

Returns a list of body parts that are injured above a specified threshold.

Parameters:

  • threshold (Integer) (defaults to: 1) —

    The injury threshold to check against, defaults to 1.

Returns:

  • (Array<Symbol>) —

    An array of injured body parts.



428
429
430
 
# File 'documented/gemstone/creature.rb', line 428

def injured_locations(threshold = 1)
  @injuries.select { |_, value| value >= threshold }.keys
end

#low_hp?(threshold = 25) ⇒ Boolean

Checks if the creature instance is below a specified hit point threshold.

Parameters:

  • threshold (Integer) (defaults to: 25) —

    The hit point threshold to check against, defaults to 25.

Returns:

  • (Boolean) —

    True if below the threshold, otherwise false.



478
479
480
481
 
# File 'documented/gemstone/creature.rb', line 478

def low_hp?(threshold = 25)
  return false unless hp_percent
  hp_percent <= threshold
end

#mark_fatal_crit! ⇒ void

This method returns an undefined value.

Marks the creature instance as having a fatal critical hit.



415
416
417
 
# File 'documented/gemstone/creature.rb', line 415

def mark_fatal_crit!
  @fatal_crit = true
end

#max_hp ⇒ Integer

Retrieves the maximum hit points for the creature instance.

Returns:

  • (Integer) —

    The maximum hit points.



441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
 
# File 'documented/gemstone/creature.rb', line 441

def max_hp
  # Try template first
  hp = template&.max_hp
  return hp if hp && hp > 0

  # Fall back to combat tracker setting if available
  begin
    if defined?(Lich::Gemstone::Combat::Tracker) &&
       Lich::Gemstone::Combat::Tracker.respond_to?(:fallback_hp)
      fallback = Lich::Gemstone::Combat::Tracker.fallback_hp
      return fallback if fallback && fallback > 0
    end
  rescue
    # Ignore errors accessing tracker
  end

  # Last resort: hardcoded fallback
  400
end

#position_to_tier(pos) ⇒ Integer?

Converts a position string to a tier number.

Parameters:

  • pos (String, Integer) —

    The position to convert.

Returns:

  • (Integer, nil) —

    The corresponding tier number, or nil if not valid.



310
311
312
313
314
315
316
317
 
# File 'documented/gemstone/creature.rb', line 310

def position_to_tier(pos)
  case pos
  when "decent", 1, "1" then 1
  when "good", 2, "2" then 2
  when "excellent", 3, "3" then 3
  else nil
  end
end

#remove_status(status) ⇒ void

This method returns an undefined value.

Removes a status effect from the creature instance.

Parameters:

  • status (String) —

    The status to remove.



272
273
274
275
276
 
# File 'documented/gemstone/creature.rb', line 272

def remove_status(status)
  @status.delete(status)
  @status_timestamps.delete(status)
  respond "  -status: #{status}" if $creature_debug
end

#reset_damage ⇒ void

This method returns an undefined value.

Resets the damage taken for the creature instance to zero.



491
492
493
 
# File 'documented/gemstone/creature.rb', line 491

def reset_damage
  @damage_taken = 0
end

#set_ucs_position(position) ⇒ void

This method returns an undefined value.

Sets the UCS position for the creature instance.

Parameters:

  • position (String, Integer) —

    The new position to set.



322
323
324
325
326
327
328
329
330
331
332
 
# File 'documented/gemstone/creature.rb', line 322

def set_ucs_position(position)
  new_tier = position_to_tier(position)
  return unless new_tier

  # Clear tierup if tier changed
  @ucs_tierup = nil if new_tier != @ucs_position

  @ucs_position = new_tier
  @ucs_updated = Time.now
  respond "  UCS: position=#{new_tier}" if $creature_debug
end

#set_ucs_tierup(attack_type) ⇒ void

This method returns an undefined value.

Sets the UCS tier-up for the creature instance.

Parameters:

  • attack_type (String) —

    The type of attack that triggered the tier-up.



337
338
339
340
341
 
# File 'documented/gemstone/creature.rb', line 337

def set_ucs_tierup(attack_type)
  @ucs_tierup = attack_type
  @ucs_updated = Time.now
  respond "  UCS: tierup=#{attack_type}" if $creature_debug
end

#smite! ⇒ void

This method returns an undefined value.

Marks the creature instance as smote.



345
346
347
348
349
 
# File 'documented/gemstone/creature.rb', line 345

def smite!
  @ucs_smote = Time.now
  @ucs_updated = Time.now
  respond "  UCS: smote!" if $creature_debug
end

#smote? ⇒ Boolean

Checks if the creature instance is currently smote.

Returns:

  • (Boolean) —

    True if smote, otherwise false.



353
354
355
356
357
358
359
360
361
362
363
 
# File 'documented/gemstone/creature.rb', line 353

def smote?
  return false unless @ucs_smote

  # Check if smite effect has expired
  if Time.now - @ucs_smote > UCS_SMITE_TTL
    @ucs_smote = nil
    return false
  end

  true
end

#statuses ⇒ Array<String>

Returns a duplicate of the current statuses of the creature instance.

Returns:

  • (Array<String>) —

    An array of current status effects.



301
302
303
304
 
# File 'documented/gemstone/creature.rb', line 301

def statuses
  cleanup_expired_statuses # Clean up expired statuses first
  @status.dup
end

#template ⇒ CreatureTemplate?

Retrieves the template associated with this creature instance.

Returns:

  • (CreatureTemplate, nil) —

    The associated creature template, or nil if not found.



239
240
241
 
# File 'documented/gemstone/creature.rb', line 239

def template
  @template ||= CreatureTemplate[@name]
end

#ucs_expired? ⇒ Boolean

Checks if the UCS data for the creature instance has expired.

Returns:

  • (Boolean) —

    True if expired, otherwise false.



375
376
377
378
 
# File 'documented/gemstone/creature.rb', line 375

def ucs_expired?
  return true unless @ucs_updated
  (Time.now - @ucs_updated) > UCS_TTL
end