Module: Lich::Common::CreatureBase::InstanceMethods

Defined in:
documented/common/creature/creature_base.rb

Overview

Per-instance transient status and classification tracking driven by the <crtrStatus> feed. The host class must call #initialize_status_tracking from its own initialize and expose @name/@id (used only for debug headers).

Instance Method Summary collapse

Instance Method Details

#add_status(status, duration = nil) ⇒ void

This method returns an undefined value.

Adds a status to the creature.

Normalizes to String so callers can pass symbols from message-based status parsing or strings from <crtrStatus>; both sources then land in the same status entries and match #has_status?.

Parameters:

  • status (String, Symbol) —

    canonical status name.

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

    optional expiration duration in seconds; falls back to STATUS_DURATIONS when omitted.



431
432
433
434
435
436
437
438
439
440
441
442
443
444
 
# File 'documented/common/creature/creature_base.rb', line 431

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

  @status << status

  duration ||= STATUS_DURATIONS[status.downcase]
  if duration
    @status_timestamps[status] = Time.now + duration
    debug_log("+status: #{status} (expires in #{duration}s)")
  else
    debug_log("+status: #{status} (no auto-expiry)")
  end
end

#cleanup_expired_statuses ⇒ void

This method returns an undefined value.

Drops any timed statuses whose expiry has passed.



460
461
462
463
464
465
466
467
468
469
 
# File 'documented/common/creature/creature_base.rb', line 460

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)
    debug_log("~status: #{expired_status} (auto-expired)")
  end
end

#crtr_flag?(key) ⇒ Boolean

Checks a classification flag captured from <crtrStatus>.

Unlike template tri-state facts, live XML flags are always-sent booleans, so an unknown or unseen flag is false, not nil.

Parameters:

  • key (String, Symbol) —

    classification key, e.g. :hostile.

Returns:

  • (Boolean) 


522
523
524
 
# File 'documented/common/creature/creature_base.rb', line 522

def crtr_flag?(key)
  @crtr_flags[key.to_sym] || false
end

#flag_active?(key) ⇒ Boolean

Checks whether a status or classification flag is active.

The two vocabularies are intentionally disjoint, so callers can filter on any known flag name without caring which bucket stores it.

Parameters:

  • key (String, Symbol) —

    status or classification key.

Returns:

  • (Boolean) 


533
534
535
 
# File 'documented/common/creature/creature_base.rb', line 533

def flag_active?(key)
  has_status?(key) || crtr_flag?(key)
end

#has_status?(status) ⇒ Boolean

Checks whether a specific status is active (after expiring stale ones).

Parameters:

  • status (String, Symbol) —

    canonical status name.

Returns:

  • (Boolean) 


475
476
477
478
 
# File 'documented/common/creature/creature_base.rb', line 475

def has_status?(status)
  cleanup_expired_statuses
  @status.include?(status.to_s)
end

#initialize_status_tracking ⇒ void

This method returns an undefined value.

Initializes the tracking ivars. Call from the host class initialize.



415
416
417
418
419
 
# File 'documented/common/creature/creature_base.rb', line 415

def initialize_status_tracking
  @status = []
  @status_timestamps = {}
  @crtr_flags = {}
end

#remove_status(status) ⇒ void

This method returns an undefined value.

Removes a status from the creature.

Parameters:

  • status (String, Symbol) —

    canonical status name.



450
451
452
453
454
455
 
# File 'documented/common/creature/creature_base.rb', line 450

def remove_status(status)
  status = status.to_s
  @status.delete(status)
  @status_timestamps.delete(status)
  debug_log("-status: #{status}")
end

#statuses ⇒ Array<String>

Returns a copy of the currently-active statuses (after expiry).

Returns:



483
484
485
486
 
# File 'documented/common/creature/creature_base.rb', line 483

def statuses
  cleanup_expired_statuses
  @status.dup
end

#sync_crtr_status(attrs) ⇒ void

This method returns an undefined value.

Reconciles status and classification from a <crtrStatus> tag.

The tag is a full snapshot of what is currently active, not a delta. A missing flag, or a flag set to "0", means inactive even if it was active a moment ago, so absent known flags are cleared rather than ignored.

Parameters:



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

def sync_crtr_status(attrs)
  CRTR_STATUS_FLAGS.each do |xml_name, status|
    if attrs[xml_name] == '1'
      add_status(status)
    elsif @status.include?(status)
      remove_status(status)
    end
  end

  CRTR_CLASSIFICATION_FLAGS.each do |xml_name, key|
    new_value = (attrs[xml_name] == '1')
    debug_log("~flag: #{key}=#{new_value}") if debug_level == :changes && @crtr_flags[key] != new_value
    @crtr_flags[key] = new_value
  end

  report_crtr_snapshot(attrs) if %i[all active].include?(debug_level)
end