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
Constructors
- 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
Constructors
- 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
Constructors
- 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
Derivations
- $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
Constructors
- 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
Constructors
- $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
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
Attributes
- $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
Constructors
- 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.