Familiars

Overview

Mortal helpfiles give a decent overview of familiars, check them out at:

CALL BAT, CALL CAT, CALL SERPENT, CALL RAVEN, CALL FOX, CALL TOAD

FAMILIAR, FAMILIAR REQUESTS, FAMILIAR SUMMARY

VNUMs

Familiar	Mob vnum	Obj vnum
Bat	54	146
Cat	56	149
Fox	53	148
Serpent	52	144
Raven	50	147
Toad	55	145

Implementation

Many of the progs on each familiar are exactly the same from familiar to familiar; to customize the behavior, data is pulled from the various data_progs on them, as well as two special sub_progs. These data_progs (and two sub_progs) are unique to each familiar, unlike all the other progs which can be copy/pasted freely between them. There are no data_progs which are not unique to a familiar.

Most of the data_progs start with "echo_"; these are the various echoes which give the familiar its personality. There is one non-echo data_prog for each mob and obj, called "settings"; this data_prog contains some numbers which control the behavior of the familiar, for things like how picky it is, how obedient, how fast, etc.

Both special sub_progs go on the mobile form. The first of these is called "do_fight_special". This is a hook called from the more general fight_prog on each familiar, and this is where customizations for special fight powers can go.

The second special sub_prog is called "do_init_special". This is a hook called when transitioning from state 0 to state 1, so basically upon calling the mobile or turning it from obj to mob. However, it might not be called

upon login, if the mage quit out with his familiar in mobile form. Thus, do not rely on this for critical initialization! In practice it is used for things like giving the toad spectacles to wear (i.e., pure flavor).

Note that an echo data_prog can have many lines, offering options to the prog engine, which will pick one at random. More lines means more variety, which helps the familiar feel special, so add any good ones you think up! Just keep in the mind the comments for each echo, listed below, to avoid any awkwardness with the phrasing.

Settings

The settings data_prog, as noted above, controls the behaviors of the familiar.

On the obj form, this consists of just two fields:

Field 0: vnum of mob form, used to transition the obj to mob

Field 1: minimum number of pulses the familiar will remain as an obj; until this elapses, the familiar will refuse commands to become a mob again (though it will mobify upon death of the caster)

On the mob form of the familiar, there are 9 fields:

Field 0: vnum of obj form, used to transition the mob to obj

Field 1: sn of the appropriate call familiar effect. Maintaining this effect on the mob is needed to support the code, for things like proximity bonus. The obj does not need this effect.

Field 2: obedience threshold; lower is more obedient, meaning the familiar will accept more commands before getting tired. If the work score drops below this number, commands are refused. See sub_prog do_calculate_obedience for implementation details.

Field 3: speed of the familiar, from 1 to 100. This represents the percentage of pulses the familiar will move to a new room, when en route to somewhere.

Field 4: patience of the familiar. This is the number of pulses the familiar will wait while scouting, before growing bored.

Field 5: rumor setting. A value of 0 means the familiar does not support rumors, and will refuse commands to do them. Positive values indicate how many pulses are needed to spread a rumor, or listen for one. Don't use negative values.

Field 6: spread rumor cooldown, in pulses. This is the number of pulses the familiar will wait after spreading a rumor before it is willing to spread another.

Field 7: boredom pulses. This is the number of pulses the familiar can be idle before becoming bored (which right now just means it gives a boredom echo, with no mechanical change).

Field 8: pickiness, higher is more picky about its food. Basically when testing whether the familiar likes a given food vnum, there is a seeded random call from 0 to this number; only on a 0 result will the familiar like it.

Mob Echoes

Fires when the mob becomes an obj

>data_prog echo_on_become_object

Fires when told to flee

>data_prog echo_on_flee

Fires when the mob refuses to do a command

>data_prog echo_on_disobedience

Fires when the mob doesn't recognize the command

>data_prog echo_on_unrecognized_command

Fires when told to remember a location

>data_prog echo_on_location_remembered

Fires if told to do something which requires a remembered room, but no room is remembered

>data_prog echo_on_location_missing

Fires if there is no path to a remembered room when it is needed

>data_prog echo_on_location_unpathable

Fires when beginning the walk to fetch or deposit something

>data_prog echo_on_walk_begun

Fires upon returning to the master with a fetched item, right before giving the item to the master

>data_prog echo_on_fetch_success

Fires upon returning to the master after a failed fetch attempt

>data_prog echo_on_fetch_failure

Fires if told to deposit, but has nothing in inventory

>data_prog echo_nothing_to_deposit

Fires upon returning to the master after a failed deposit attempt (generally from a path that got closed after starting)

>data_prog echo_on_deposit_failure

Fires upon returning to the master after depositing something (or somethings)

>data_prog echo_on_deposit_success

Fires if told to safeguard something, but cannot resolve what it is

>data_prog echo_no_safeguard_object

Fires when told to safeguard something, and recognized it (i.e., is prepared to safeguard)

>data_prog echo_safeguard_object_ready

Fires when returning a safeguarded item to a master who died

>data_prog echo_on_safeguard_success

Fires when returning to a master who died, when unable to safeguard an item; be generic, as this also happens if nothing was specified to safeguard

>data_prog echo_on_safeguard_failure

Fires when told to scout, but cannot resolve a PC from the string

>data_prog echo_no_pc_to_scout

Fires when scouting begins

>data_prog echo_scouting_start

Fires REMOTELY when scouting succeeds; make sure this is mpechoat, tell, or something else for remote (or yell if you want the familiar to be useless and obnoxious ;))

>data_prog echo_on_scouting_success

Fires REMOTELY when mob gets bored of scouting and gives up, without ever sensing the PC; same caveat as above

>data_prog echo_on_scouting_failure

Fires when told to listen for a rumor

>data_prog echo_on_rumor_listen_start

Fires when about to relate a rumor to the master (with mprumor, so it will be a 'say')

>data_prog echo_on_rumor_listen_end

Fires if this familiar does not do rumors, when a rumor is requested. Fill this out for all familiars even if they support rumors, so that we can safely toggle it on and off if we want.

>data_prog echo_on_rumors_unsupported

Fires when told to spread a rumor, but already did so recently

>data_prog echo_on_spread_rumor_refused

Fires when told to spread a rumor, but the master hasn't said what yet

>data_prog echo_on_spread_rumor_waiting

Fires when told to spread a rumor and is ready to begin (master supplied rumor already)

>data_prog echo_on_spread_rumor_start

Fires upon returning from spreading a rumor

>data_prog echo_on_spread_rumor_end

Fires when told to stop doing its current task

>data_prog echo_on_cancel

Fires when familiar transitions to bored state

>data_prog echo_on_bored

Fires randomly from time to time

>data_prog echo_on_random

Fires when handed bad food. The familiar will then drop the food.

>data_prog echo_on_food_bad

Fires when handed good food; the familiar will then eat the food

>data_prog echo_on_food_good

Obj Echoes

Fires when turning into a mobile from an object

>data_prog echo_on_become_mobile

Fires when requested to turn into a mobile, but too recently became an obj

>data_prog echo_on_remaining_object

Fires when ready to become a mobile again

>data_prog echo_on_ready_to_become_mobile

Fires on an unrecognized command

>data_prog echo_on_unrecognized_command

Fires randomly during fights

>data_prog echo_on_fight

Var/String Fields

These are the fields tracked by the familiar. Note that when transitioning from mob to obj or vice versa, all fields get copied.

Vars

v0: work tracker; incremented when one of the following tasks is requested (fetch, deposit, scout, spread rumor, listen for rumor), decremented each game day or when good food is given, to a minimum of 0. Checked for obedience.

v1: used by the obj form to track how many pulses are left until it can be made a mob again

v2: this is the state tracker, used to maintain the current task/state of the familiar. See the state tracking section below for details on what the values mean.

v3: used to store the room vnum remembered from the 'remember' task

v4: tracks the number of pulses left for scouting/listening for rumor/spreading rumor

v5: used to store the room vnum for scouting; since the caster will pull the familiar with him when he moves, the familiar will track back here to keep scouting

v6: tracks the number of pulses left before being able to spread another rumor

v7: tracks the number of pulses the familiar has been idle (mob form), for boredom tracking. Reset when spoken to.

v8, 9: these are used as local vars in progs, or to pass values between progs. Don't store anything persistent in them, as progs may override it!

Strings

s0: the player-given familiar name, which is also the mob short desc

s1: the string being requested in a fetch task. This is stored in its unresolved state, and is resolved upon entering the target room.

s2: name of object to safeguard, stored in its resolved state

s3: name of PC to scout for, stored in its resolved state

s4: text of rumor to spread

s5 - s8: unused

s9: this is used as local vars in progs, or to pass values between progs. Don't store anything persistent here, as progs may override it!

State Tracking -- the v2 var

0: cannot receive commands right now. This is used immediately after transitioning to/from obj, to prevent triggering on the same text which changed the form. It lasts only one pulse.

1: idle state, can receive commands. Boredom increases while in this state. If separated from master, will track back to him.

2: currently fetching an item (tracking to remembered room)

3: returning from fetching an item (tracking to master)

4: currently depositing item/items (tracking to remembered room)

5: returning from depositing item/items (tracking to master)

6: returning from safeguarding an item (tracking to master)

7: currently scouting (tracking to scout room, or sitting there)

8: currently listening for a rumor (hangs out in room 200 for a bit)

9: currently waiting for master to state rumor to spread

10: currently spreading rumor (hangs out in room 200 for a bit)