Object Model Reference

CARPE DIEM v2000.11.10

Introduction

This document aims to be a brief but comprehensive overview and help guide to the object networks used in the CARPE DIEM roguelike game engine.

It is certainly incomplete and inaccurate in places, but is better than no documentation at all (knock on wood.) All information contained herein is subject to change, in terms of interface, naming, and implementation. Interfaces marked with (???) are extremely likely to change.

Object Framework

Members on objects are of two basic types: methods, which are Perl functions, and attributes, which are mutable data members.

Kinds of methods include: derivations which return a value only; mutations which change the state of the object (and which may or may not return a value); and constructors, which return a new object while not changing the state of the old object (if any.) Constructors which create a new object based on an old object are sometimes called factories.

Kinds of attributes include event handlers, which are like methods in that they are executable. Names of event handlers always begin with on_, and their data type is always a string (which is usually simply evaluated by Perl's built-in mechanism.)

Part I. Utility Classes

Dice - objects which can be rolled to yield a random integer
Distribution - objects which can be picked to yield a random object
Fuses - objects which maintain sequences of arbitrary future events

Dice

Dice->new(\$count, \$faces, [\$bonus]) \ Creates and returns a new Dice object with the given attributes.
\$dice->improve(+\$integer) (??? adjust_plus) \ Returns a new Dice object with an altered 'plus' bonus modifier. This does not affect the given \$dice object.
\$dice->improve_faces(\$factor) (??? scale_faces) \ Returns a new Dice object with its faces altered by a factor. This does not affect the given \$dice object.

Derivations
\$dice->roll \ Returns a random integer, the range and frequency distribution of which is determined by the number of dice, the number of faces on each die, and a 'plus' bonus modifier.

Attributes
\$dice->{count} \ The number of dice the object represents.
\$dice->{faces} \ The number of faces represented on each die.
\$dice->{plus} \ The bonus modifier added to the basic dice roll.

Distribution

Distribution->new(\$probability => \$object, ...) \ Creates and returns a new Distribution object with the given probability-to-object associations.

Derivations
\$distribution->pick \ Returns a random object, the frequency distribution of which is determined by the Distribution object's probability percentages.

Mutations
\$distribution->scale(\$factor) (??? scale_probabilities) \ Alters all of the Distribution object's probability percentages by \$factor, a rational number.

Fuses

Fuses->new() \ Creates and returns a new, empty Fuses object. Generally speaking, only one Fuses object is required for the entire engine.

Derivations
Fuses->current() \ Returns a reference to a hashtable which describes the currently expiring fuse; used in scripts set up in fuses to modify the fuse for the next pass.

Mutations
\$fuses->tick \ Causes all expired fuses to fire, and all non-expired fuses to come one time unit closer to firing.
\$fuses->add(\$script, \$fuse_duration, \@argument) (??? name) \ Adds a new fuse to the Fuses object.

Part II. Multiple Superclasses

Physical - objects with a physical presence
Cloneable - objects which can be copied and bred
Saveable - objects which can be loaded and saved

Constructors

These object classes do not have constructors.

Physical

\$physical->accusative \ Returns the appropriate accusative pronoun (him, her, it.) Occurances of <him> in format strings is replaced by this.
\$physical->possessive \ Returns the appropriate possessive pronoun (his, her, its.) Occurances of <his> in format strings is replaced by this.
\$physical->plural (???) \ Returns the plural form of the name of the Physical object in question.
\$physical->dist(\$physical) \ Returns the distance between the two Physical objects in question.
\$physical->in_bounds([\$x, \$y]) \ Returns a boolean value indicating whether this Physical object (or the given (x,y) coordinates, if any,) is within the bounds of it's Region object indicated in {location}.
\$physical->screenx() | ->screeny() \ Returns the x- (or y-) position on the screen where this Physical object would be displayed.

Mutations
\$physical->display() \ Redraws the Physical object on the screen if it happens to be in the line of sight of the leader.
\$physical->undisplay() \ Erases the Physical object from the screen.
\$physical->seen(\$physical, "message") \ Broadcasts an action taken by the Physical object to every receiving Physical object within line of sight and range.
\$physical->hurt(\$force, \$perpetrator, \$body_part) \ Causes the Physical object to take damage. The amount of damage is indicated by \$force, and the Actor which is causing the damage receives experience points, if any, should the Physical object be destroyed.
\$physical->heal(\$force, \$perpetrator, \$body_part) \ Opposite of hurt. Not really implemented.

Attributes
\$physical->{name} \ String containing the conversational name of the object.
\$physical->{identity} \ String containing the secret identity of the object.
\$physical->{sex} \ String containing the sex of the object; must currently be only one of: 'Male', 'Female', or 'Neuter'.
\$physical->{proper} \ Boolean indicating whether the object has a proper name.
\$physical->{damage} \ A Force object which indicates the potential damage caused to an opponent when this Physical object is used as a melee weapon.
\$physical->{projectile} \ A Force object which indicates the potential damage caused to an opponent when this Physical object is used as a thrown (not launched) weapon. (Launching weapons use a version of this Force modified via \$force->{dice}->improve_faces().)
\$item->{hitbonus} (??? accuracy, Dice) \ An integer which indicates the accuracy bonus gained by this Physical object (be it an Item or an Actor) in combat (be it melee or missile.)
\$physical->{displayed} (??? _displayed) \ A boolean indicating whether this Physical object is already displayed on the screen, altered by the display and undisplay methods.
\$physical->{lightsource} (??? light_range, light_duration) \ A boolean indicating whether this Physical object acts as a source of light.
\$physical->{count} \ An integer which indicates how many instances of the same Physical object represents. For example, a single Physical object can represent a group of a dozen arrows, as long as the arrows do not differ from each other in any way.
\$physical->{magic} (??? A:is_magical) \ A boolean which indicates whether this Physical object is magical.
\$physical->{curse} (??? A:is_cursed, on_remove) \ A boolean which indicates whether this Physical object is cursed.
\$physical->{lore} (???) \ A string which contains some background information about the Physical object.
\$physical->{weight} \ An integer which indicates how heavy this Physical object is (assuming {count} is 1; to get the weight of the entire group multiply {count} by {weight}.)
\$physical->{aeroweight} (??? drag_coefficient) \ An integer which indicates the effective weight of this Physical object when it is thrown (tweaked due to aerodynamics, throwing motion, etc.)
\$physical->{indestructible} (??? on_destroy) \ A boolean indicating that the Physical object cannot be destroyed, typically found on edge walls in dungeons.
\$physical->{durability} (??? {max}{constitution}) \ A boolean indicating how much damage the Physical object can at most sustain before it is destroyed.
\$physical->{condition} (??? {op}{constitution}) \ A boolean indicating how much damage the Physical object can currently sustain before it is destroyed.
\$physical->{resists} \ A Resistances object, which describes which forces this Physical object is resistant or subsceptible to.
\$physical->{location} \ The Region object where this Physical object is located, if 'on the ground' and not being carried by an Actor.
\$physical->{x} | ->{y} \ The x (or y) coordinate of the Physical object, relative to the map in the object's {location} Region object.
\$physical->{appearance} \ A string which exists as a key in the global appearance table %::sc. Usually a fairly generic name like 'dragon' or 'fruit' will be found here.
\$physical->{color} (??? background, transparent) \ A string which exists as a key in the global color table.

Physical Classes

All of these classes are subclasses of Physical (among other things.) As such, they inherit the methods and attributes of Physical objects as described above.

Actor - objects with agency
Item - objects which can be carried
Terrain - objects which be travelled on/around

Actor

undocumented

Derivations
\$actor->has(\$object) \ Determines whether the Actor object possesses a certain object (an Item or a Talent.) Returns said object if it is possessed, or undef if not. Talents are compared by name. Items are compared by full identity. If the Item argument has a {count}, then the Item in the Actor's inventory must be at least that {count}.

Attributes
\$actor->{hair_type} | ->{eye_type} | ->{skin_type} \ Strings containing the short descriptions of the physical attributes of this Actor.
\$actor->{hair_color} | ->{eye_color} | ->{skin_color} \ Strings containing the color descriptions of the physical attributes of this Actor. These can map to screen colors for player characters.
\$actor->{race} \ String containing the name of the race of beings to which this Actor belongs. Not implemented particularly strongly.

\$actor->{carcass} (??? on_death) \ Boolean indicating whether this Actor leaves a carcass after it's death.

  'lit'            => 0,  # value *derived* from holding light source
  'incapacitated'  => 0,  # value *derived* from operating stats

\$actor->{effect} (???) \ Integer indicating how many turns of effect are left to apply to this Actor. Effect may be one of: 'blind', 'deaf', 'dumb', 'confused', 'paralyzed', 'placid', and 'blurry'.
\$actor->{bodypart} \ Item which is currently being wielded on the given body part. Bodypart may be one of: 'head', 'neck', 'shoulders', 'arms', 'rwrist', 'lwrist', 'hands', 'rfinger', 'lfinger', 'rhand', 'lhand', 'torso', 'waist', 'legs', 'rankle', 'lankle', and 'feet'.
\$actor->{totalhits} \ Integer measurement of the total number of damaging hits this Actor has taken, for statistical purposes.
\$actor->{blockedhits} \ Integer measurement of the total number of hits this Actor has sucessfully blocked, for statistical purposes.
\$actor->{totalswings} \ Integer measurement of the total number of attacks (hit or miss) this Actor has made, for statistical purposes.
\$actor->{damagingswings} \ Integer measurement of the total number of damaging attacks Actor has sucessfully made, for statistical purposes.
\$actor->{party} \ Party object to which the Actor belongs.
\$actor->{encounter} \ Encounter object which is started when another Actor interacts with this Actor.

\$actor->{target} \ Actor object which is this current target of this Actor.

  'combat'         => 'Attack',  # some creatures will Flee or Bargain instead
  'noncombat'      => 'Wander',
  'body_aim'       => 'dumb_biped',
  'experience'     => 0,
  'belongings'     => [],
  'talents'        => [],
  'domhand'        => 'rhand',
  'on_move'        => '',

\$actor->{max}{stat} \ Integer maximum stat for this Actor. Stat may be one of: 'strength', 'constitution', 'dexterity', 'intelligence', 'spirit', and 'charisma'.
\$actor->{op}{stat} \ Integer operating (current) stat for this Actor. Stat may be one of: 'strength', 'constitution', 'dexterity', 'intelligence', 'spirit', and 'charisma'.

Mutations
\$actor->heal_all() \ Sets the operating stats of the Actor to the maximum stats of the Actor.
\$actor->remove_talents() \ Remove all Talents with a skill level of 0% or less from this Actor.
\$actor->adjust(\$stat, \$delta) \ Change an operating stat by a certain amount, possibly killing the Actor in the process.
others undocumented

Attributes
undocumented

Item

\$item->bunch(\$integer) \ Returns a new Item object with its {count} set to a specific integer. This does not affect the given \$item object.

Derivations
\$item->combinable(\$item) \ Returns a boolean indicating whether the two Item objects are identical (and can be combined into a single Item by adding their counts together.)

Mutations
\$item->identify \ Reveals the secret identity of this Item, setting the conversational name of it to the same.
\$item->perceive_value(\$item) \ Causes this Item object to be perceived to be priced by a certain number of other Item objects, by it's owner.
\$item->useup(\$consumer, [\$delta]) (???) \ Causes a certain number of this Item object to be used up in some way by an Actor object. Dangerously ambiguous, needs clarification.
\$item->usemissile(\$consumer???) (???) \ Causes one of this Item object to be used up in a missile-weapons way by an Actor object. Dangerously ambiguous, needs clarification.
\$item->use(\$actor) \ Causes this Item object to be used by it's owner. This will activate it's {talent}, or the {on_use} event if the talent is not provided.

Attributes
\$item->{worn_on} \ A dictionary, mapping the body parts that this Item can be worn on as clothing or armor, to while body parts they cover when worn. Not fully implemented yet.
\$item->{written} (??? A:is_readable) \ A boolean indicating whether this Item can be read.
\$item->{food} (??? A:is_edible | is_consumable) \ A boolean indicating whether this Item can be eaten.
\$item->{beverage} (??? A:is_drinkable | is_consumable) \ A boolean indicating whether this Item can be drunk.
\$item->{body} (??? A:is_bodily) \ A boolean indicating whether this Item is part of its possessor's body. If this is the case, it will not be dropped after the Actor's death.
\$item->{defense} (??? worn_on -> covers -> composition) \ An integer which indicates the defense capability of this Item when worn.
\$item->{charges} (??? fuel) \ An integer which indicates how many charges this Item has left (wands and so forth.)
\$item->{talent} (??? consume_talent, on_use etc) \ A Talent object which indicates what thing this Item does when used or consumed (in the absence of any on_use or on_consume event).
\$item->{value} (??? _value) \ An Item object which indicates what the owner of this Item thinks it is worth.
\$item->{soul} \ An Actor object which represents the essence of a being encapsulated in this Item (figurines, pocket-monster cards, genies in lamps, etc.)

Event Handlers
\$item->{on_wear} \ This event is triggered when an Actor puts on or takes off this Item.
\$item->{on_consume} \ This event is triggered when an Actor consumes (eats, drinks, applies) this Item.
\$item->{on_use} \ This event is triggered when an Actor uses this Item.
\$item->{on_land} \ This event is triggered after this Item is thrown or fired.
\$item->{on_strike} \ This event is triggered after this Item strikes someting in melee combat.
\$item->{on_struck} \ This event is triggered after this Item is struck by something.

Terrain

undocumented

Non-Physical Classes

Talent - skills or magic employed by objects
Region - objects which maintain maps of objects
Encounter - objects which describe meetings and surprises

Talent

\$talent->{on_perform} \ Script which is called when the Talent object is performed.
others undocumented

Region

\$region->{name} \ String containing the name of the Region.
\$region->{genpattern} \ Establishes the logic used to fill out an unfilled Region object with random Terrain objects. Allowable genpatterns are:
- random - noise
- accretion - natural terrain
- recursive - unnatural terrain
- canned - based on provided map
- dungeon - room-and-hallway excavation
- gradient - gradient between several different distributions
\$region->{generated} \ A boolean indicating whether terrain for this Region has been generated yet.
\$region->{sizex} | ->{sizey} \ Integers indicating how many cells wide/tall this Region is.
\$region->{offsetx} | ->{offsety} \ Integers indicating the scrolled position of the map of this Region when displayed.

\$region->{worldx} | ->{worldy} \ Integer coordinates indicating this Region's position in the world map.

  'map'          => [],
  'lit'          => [],
  'actors'       => [],
  '_collmap'     => [],
  'outside'      => $::sc{dark},
  'border'       => undef,
  'ambient'      => undef,
  'terraind'     => undef,
  'terrgradn'    => undef,
  'terrgrads'    => undef,
  'terrgrade'    => undef,
  'terrgradw'    => undef,
  'monsterd'     => undef,
  'itemd'        => undef,
  'music'        => '',
  'msg'          => '',
  'template'     => '',
  'legend'       => '',

others undocumented

Encounter

Encounter->new() \ Basic constructor.
Encounter->auto(\$actor) \ Automatic constructor.

Mutations
\$encounter->begin() \ Causes the Encounter to begin, displaying menus with which the user can interact with the Actor(s).
\$encounter->attack() \ Called by begin(), causes the Encounter to degrade into attack.

Attributes
\$encounter->{actors} \ A reference to an array of Actor objects who are hosting this Encounter. When the Encounter is attached to an Actor in the first place, that Actor is automatically injected into this list.
\$encounter->{message} \ A string displayed upon initiation of the Encounter.
\$encounter->{lore} \ A string displayed upon friendly communications.
\$encounter->{persistent} \ A boolean indicating whether the Encounter is persistent. If it is not persistent, it is removed after it is activated.
\$encounter->{friendly} \ A boolean indicating whether the Encounter is friendly.
\$encounter->{itemseller} (??? on Actor) \ A boolean indicating whether the host of the Encounter is willing to sell items.
\$encounter->{itembuyer} (??? on Actor) \ A boolean indicating whether the host of the Encounter is willing to buy items.
\$encounter->{serviceseller} (??? on Actor) \ A boolean indicating whether the host of the Encounter is willing to sell services (Talent applications).
\$encounter->{servicebuyer} (??? on Actor) \ A boolean indicating whether the host of the Encounter is willing to buy services.