Latest revision as of 16:28, 19 April 2019

Hub data

   “Things are only impossible until they’re not.” – Captain Jean-Luc Picard

Overview

Hub data is stored on an individual mob, in much the same manner as shop specifics are. However, hub data is significantly more complex and supplemented by the prog system. Because of its potential power, the unusual way it interacts with other game systems, and its ability to subsume existing quest content, it has its own section rather than an especially verbose appendix within OLC Section 3: Medit.

What is hub data? Well, the short version is that it's a template used to define the parameters of quests. It was built for the expressed purpose of creating simple, radiant-style quests, dubbed tasks, because of their temporary/time-limited nature, with quests being more permanent legacy implementations. However, as the task system has expanded, it now can work existing quest content into it, obviating the distinction between the two.

For the purposes of this document, hub refers to the data stored on the mob which gives out a given task. A task on the other hand, refers to the quest content which is being performed. These are parallel systems which interact with one another in a variety of ways, so the distinction can be a bit muddy. Hubs are the origin of tasks; data related to rewards or accessibility are stored there. Tasks themselves store only the essential information to their execution.

Task Flow

Every task follows the same general progression once a task hub has been located. It is as follows:

   begin -> succeed or fail at the task -> complete

The begin command initiates a task at a task hub. This will trigger the origin mob's initial dialogue and any setup conditions the task may require. For many task types, this is automatic; however it can be supplemented, or even entirely written, in prog based on the need of the builder.

The actual performance of the task can vary wildly depending on the task type. Often, tasks are on a time limit, and should that time limit expire before you get the task reward for completion, the task will automatically fail and remove itself from the active task list.

Once you have either successfully performed the task, whatever it may be, or decided that you are unable or unwilling to do so, the task is voluntarily terminated using the complete command. This requires returning to the origin mob; once it has been done, the origin mob will perform whatever cleanup is necessary and put the character on cooldown, granting a reward if applicable and adding it to their task log.

This program flow is important to understand, especially when looking at configuration flags (cflags), discussed later in this document, which alter it. If or why you may need those flow adjustments will be apparent when in the process of designing your task.

The Hub Data Viewer

   +----------------------------------------------------------------------------------+
   | Task Hub Settings (Slot 0)                                                       |
   | Name:                        Possible Futures                                    |
   | Task type:                   6                       (Bit flip)                  |
   | Min level:                   1                                                   |
   | Max level:                   60                                                  |
   | Class filter:                [none]                                              |
   | Race filter:                 [none]                                              |
   | Ethos filter:                -1                      (All)                       |
   | Align min:                   -1000                                               |
   | Align max:                   1000                                                |
   | Config flags:                [no_enemy autocomplete]                             |
   | Target flags:                [none]                                              |
   | Target vnum (if applicable): 3781                                                |
   | Object vnum (if applicable): 0                                                   |
   | Reward type:                 1                       (Experience)                |
   | Reward value:                500                                                 |
   | Timer value:                 -1                                                  |
   +----------------------------------------------------------------------------------+

This viewer is appended to any mob which has had hub data generated for it. If this is not visible on the current mob you are working on, that's okay! It will appear when you start using hub-related OLC commands. All hub commands use the following syntax:

   hub <command> <value>

Available Commands

slot

Syntax: hub slot <value>

This specifies which slot you are using. Each time a mob is assigned hub data, it allocates four empty slots to that mob. Each of these slots can be used to store task data for separate tasks. If there are multiple tasks stored on the same mob, and these tasks overlap (that is, characters could fulfill multiple task prerequisites simultaneously), they will be issued in sequence, starting from the lowest slot, and ending at the highest.

There is code protection to keep you from attempting to assign a slot which is outside the boundaries of acceptable values. However, it is possible to expand the total number of slots available should it become necessary. In that case, please request that a coder adjust the value MAX_HUB in merc.h to whatever the new value should be.

name

Syntax: hub name "<string>"

The name command specifies the name of the task, which will be viewable via the players' tasks command. It will also display upon the completion of a task, should it not be blocked by configuration flag.

type

Syntax: hub type <value>

Type specifies what kind of task the hub slot is intended to provide. The types are as follows:

   1: Assassination.  Locate a mob and kill them.
   2: Retrieval.  An item is spawned on a mob.  Obtain the item from the mob by any means.
   3: Delivery.  An item is given at task start.  Deliver it to the target mob.
   4: Exploration.  Reach the target room.
   5: Dead drop.  An item is given at task start.  Drop it in the target room.
   6: Bit flip.  Task completion occurs when the mpbitset command toggles the specified bit to the specified position.
   7: Mass kill.  All mobs of a specific vnum are targeted.  Kill a specific number of them.
   8: Collection.  All items of a specific vnum are targeted.  Gather a specific number of them.

The bit flip task is the most open-ended, and can allow builders to invent virtually any task type they can imagine; however, it will take substantially longer to do so than it would to use a generic task type. When possible, use a generic to save yourself development time!

Bit flip is primarily intended to replace existing quest content and bring it into the task system fold. If there are other obvious generic task types which are not yet available, discuss them with your coder to determine the necessity and viability of the new type before developing a bit flip version.

min

Syntax: hub min <value>

This specifies the lower level threshold of the task in question. Characters below the specified level cannot view or accept the task.

max

Syntax: hub max <value>

Like min, this specifies the upper level threshold for the task in the current slot. Characters above the specified level can neither view nor accept the task. Should a character exceed the maximum level while performing the task or before completing it, the task automatically fails.

class

Syntax: hub class <flag>

The class command provides blacklist-style filtering for all character classes. Once a flag is set, that class is no longer able to interact with the task in the specified slot. For the sake of builder convenience, the flags used by this command are the who names of the particular class. Examples: void scholar is VSc, void templar is VTe, and so on.

This value can be turned into a whitelist by using the invert_class config flag.

race

Syntax: hub race <flag>

Like the class command, the race command also provides blacklist-style filtering for PC races. Once a race is specified, they are excluded from participating in the task defined by the current slot. This can be turned into a whitelist by using the invert_race config flag.

ethos

Syntax: hub ethos <value>

Unlike the previous two, ethos is a whitelist-style filter, in which a specified ethos becomes the only one able to perform the task in question. Since ethos filtering is rare at best, and tends to be to specifically focus on either being lawful or chaotic (rather than not lawful or not chaotic), this is how it is currently set up. In the future, should it become necessary, this may be changed to imitate the blacklist-style filtering of class and race.

amin

Syntax: hub amin <value>

Like the min command, amin established a lower bound; but instead of level, it is for alignment. Remember that the lowest possible value is -1000. This is using the stock alignment system, not karma, so -750 to -1000 is evil, 750 to 1000 is good, and everything else is neutral.

amax

Syntax: hub amax <value>

The upper bound for alignment. See above for details of how the stock alignment system defines its values.

cflags

Syntax: hub cflags <flag>

The cflags command handles the definition of configuration flags, which encompass settings for the hub data which alter the behavior of the task in the current slot. These effects can be subtle or significant, and are defined below:

   1. area_vnum: The value of target vnum specifies an area vnum rather than a mob vnum or bit value.
   2. expand_domain: Currently inert.
   3. no_friend: Characters who are friends of the hub's parent mob's faction cannot interact with the specified task.
   4. no_enemy: Characters who are enemies of the hub's parent mob's faction cannot interact with the specified task.
   5. no_inert: Characters who are neutral to the hub's parent mob's faction cannot interact with the specified task.
   6. autocomplete: Upon completing the task, the reward is granted without returning to the task originator.
   7. no_echo: Upon completing the task, no echo is provided to the character who completed it.
   8. hub_cooldown: When anyone completes the task, no character may take the task until the cooldown timer has ended.
   9. level_cap: The task cannot target any mob whose level exceeds that of the character taking the task.
   10. repeat_perm: This flag allows a permanent duration task to be repeated if completed.
   11. no_repeat: when set, this flag reads from a character's task log, and if completed, will not allow repetition.
   12. house_only: when set, only characters with the same clan value as the hub's parent mob will be permitted.
   13. task0: when set, only characters who have completed the task in slot 0 can interact with the specified task.
   14. task1: when set, only characters who have completed the task in slot 1 can interact with the specified task.
   15. task2: when set, only characters who have completed the task in slot 2 can interact with the specified task.
   16. task3: when set, only characters who have completed the task in slot 3 can interact with the specified task.
   17. invert_class: this flag changes the class bit value from a blacklist to a whitelist.
   18. invert_race: this flag changes the race bit value from a blacklist to a whitelist.

The intention of a flag like no_echo is for unmarked tasks which are logged and/or offer a reward. An example of this type is the magic mouth (vnum 3726) in the School of Heroes; it offers trivia questions and an experience reward, but isn't visibly treated like a task.

tflags

Syntax: hub tflags <flag>

Targeting flags are set via the tflags command, which applies filters to the automatic target acquisition handled in-code for various task types. When target vnum specifies a mob range (that is, the area_vnum> flag is not in use and a specific vnum has not been assigned), these flags are used to determine what mobs are viable targets for the task in question. Those filters include:

   1. no_good: Good-aligned targets are excluded.
   2. no_neutral: Neutral-aligned targets are excluded.
   3. no_evil: Evil-aligned targets are excluded.
   4. animals_only: Only mobs with act_animal are allowed to be targeted.
   5. no_animals: No mobs with act_animal are allowed to be targeted.
   6. demons_only: Only mobs who are considered demons are able to be targeted.
   7. no_demons: No mobs who are considered demons are able to be targeted.
   8. sapients_only: Only PC races can be used as targets for the specified task.
   9. no_sapients: No PC races can be used as targets for the specified task.
   10. undead_only: Only mobs with act_undead or form_undead will be targeted.
   11. no_undead: No mobs with act_undead or form_undead will be targeted.
   12. insects_only: Only insectoid mobs will be targeted, using either form bits or race prototypes.
   13. no_insects: No insectoid mobs will be allowed to be targeted.

Remember, the level_cap configuration flag can (and should) be used in some cases to prevent characters from fighting overly powerful mobs. No generic kill task should have someone accidentally tasked to kill King Gogoth!

tvnum

Syntax: hub tvnum <value>

The tvnum value has a variety of uses. When left undefined, the task target for assassination, retrieval, or delivery tasks will be generated globally by code. This could include virtually any mob that isn't filtered out by the flags assigned in tflags (see above). This is intended for truly radiant-style tasks, mostly for the most ambitious of bored heroes.

When used in conjunction with the area_vnum configuration flag, it contains the area vnum where the target should be located. Again, that target is generated by code within the region, and pays heed to level_cap and to the parameters specified in tflags. Even then, some cases will be excluded (such as giving a target in the Clockmaker's Mansion after the character is above the level threshold for entrance into that area, or immortal-only rooms).

When given a specific vnum for task type 6 (bit flip), it contains the value of the bit which must be flipped to complete the task in question. For example, if it contained 3781, the task would complete upon the prog command, mpbitset <character> 3781 1.

In the case of dead drop or exploration tasks, tvnum is used to specify the room vnum that a character must reach to complete the task defined in the present slot. It does so because in those task types, there are no mobs interacting with the task itself at all, leaving the variable free for ulterior use.

However, in some cases, the specified vnum will correlate to a mob. The mass kill task will flag all mobs of that vnum with the (Targeted) flag; other task types attempt to find more specific instances, as they flag one mob at a time. In those cases, it will attempt to find all copies of that mob vnum which are in play, and randomly select one of them to become the target. Should there be no mobs of that vnum in active play, the task assignment will fail. Note that in many cases, this will be used on specific targets where there will only ever be one copy, such as a Death Knight-- but it may also work as a class of duplicated mobs, such as the khil'ayum in Astral Prison.

The outlier case is the collection task, in which the value stored by tvnum assigns the number of items to be collected.

ovnum

Syntax: hub ovnum <value>

The ovnum value contains an object vnum for the delivery, retrieval, dead drop, and collection task types. When specified, it loads an instance of the item either on the target mob (for retrieval), gives it to the character beginning the task (delivery, dead drop), or flags all items of the given vnum (collection). If an item is created, upon the creation of the item, it is given an affect which will allow the character seeking or delivering it to discern that it is the task item and not a random thing they were already carrying. Should this item be destroyed, lost, or what have you, the quest can be failed but not completed successfully. Conversely, collection does not create items, and one can obtain them from any source.

It should be noted that upon loading the item in question, its load_prog will trigger as if it were loaded via reset. Use this to configure the item as necessary for the task at hand; in some cases, the object may be a placeholder vnum which is rewritten in prog, and in others, it may be ignored entirely.

This value is also used by the mass kill task type. In it, this field stores the value of the number of mobs of the specified vnum someone must kill to complete the task. The OLC editor will change its output to suggest this once type 7 has been selected; it is still modified using the same syntax as the others.

reward

Syntax: hub reward <value>

The reward value contains the type of reward the character will receive if they complete the task in the specified slot. There are a number of possible rewards, which are outlined below:

   1. Experience.  A character receives experience points.
   2. Faction.  A character receives a faction adjustment (positive or negative).
   3. Money.  A character receives an amount of money.
   4. Karma.  A character receives a karma adjustment (positive or negative).
   5. Item.  A character receives an item, with its vnum defined in value (see below).
   6. Bit flip.  A character has a bit set or unset based on the integer defined in value.
   7. Skill up.  A character receives +5% to the skill vnum defined in value.

In most cases, the value variable stores the amount received, with its default being 0. In the item case, it stores the vnum of the reward item; the bit flip case, the bit to be flipped; and skill up, the skill vnum to be increased.

value

Syntax: hub value <value>

Value is an integer which stores how much experience, faction, money, or karma a character should receive for completing a task. In many cases, tasks are repeatable, so these values should be sane relative to the cooldown specified in the timer value.

In the case of an item, value contains the vnum of an object. An instance of that object is then loaded, its load_prog is activated, and then given to the character in question. This should allow significant flexibility for you, the builder, on what those items can do or be. As well, it should prevent other characters from attempting to steal the reward.

The other possibility is a bit flip reward. Value then contains the vnum of the bit to be flipped or unflipped (with positive values specifying the bit be set to ON, and negative values specifying the bit be set to OFF). In those cases, any other rewards or benefits from the task in question need to be handled in prog.

timer

Syntax: hub timer <value>

The value specified will determine the duration of the task, and the cooldown of the task on success or failure. Those values are as follows:

   1. Duration of the task before it expires: 4 * timer.
   2. Cooldown after task success before it can be repeated: 2 * timer.
   3. Cooldown after task failure before it can be repeated: 1 * timer.

Tasks may also be of a permanent duration, if they use -1 as their timer value. Such tasks are saved into a player's pfile and loaded when they reconnect to the game. This is important, as many tasks are effectively timed radiant quests which expire upon quit. These sorts of tasks have special rules: if completed, they have a reuse timer of 0 (and as such, should be bit flip rewards or no_repeat in nearly all cases); if failed, they have a standard reuse timer of 12.

Prog System Linkage

It is possible to use the prog system at various stages of the task process. Task dialogue is intentionally generic, and can be overwritten by proper use of a data_prog with the appropriate name. When such a prog exists, the task handler for the task in question will automatically execute it, much in the manner one might expect from, say, an eat_prog. This automatic execution is intended for two purposes:

• To allow the resolution of symbols such as $N, $q, and $Q.
• To give opportunities for builders to insert their own prog code to increase the cleverness of their tasks.

To specify your own data_prog rather than use the woefully generic dialogue (which is intended solely for debugging purposes and crash prevention), it must follow the following naming conventions:

   >data_prog start_dialogue0
   >data_prog nostart_dialogue0
   >data_prog complete_dialogue0
   >data_prog nocomplete_dialogue0
   >data_prog noitem_dialogue0

...where the integer value at the end of the name is the hub data slot you want to specify. Thus, it could be >data_prog start_dialogue1 if it were executed on the successful start of a task being read out of hub slot 1.

Nostart specifies when someone attempts to start a task but it fails to do so (such as the task target being unable to be resolved, such as all of the khil'ayum in Astral Prison being dead). Nocomplete is the prog which is executed when a task fails-- that is, when one completes the task but does not meet the requirements to receive a reward. In the case of retrieval and collection tasks, noitem handles cases where someone had the item in question (and thus completed the task), but then lost it before reaching the origin mob. In such a case, the task fails.

For multiple hub slots, multiple data_progs will be required, and will never interact with one another under normal circumstances.

Functional Examples

The following is a listing of mobs with implemented tasks. They provide some examples of how to make different task types work, and how to make use of various filtering or configuration flags. If a particularly novel task is created, add it here! It's best to direct other builders to the things you've created if you think it will be helpful.

• Bellaqe (vnum 8227): Area-specific undead-only assassination tasks.
• Ichiaj Chidak (vnum 3756): Basic retrieval. Obtain tail from rat, return it to task-giver.
• Arafis Tindel (vnum 3700): Basic delivery. Take list from him to Laoti and return to him.
• Teloqi (vnum 3718): Retrieval variant; get ring from pool (target location) and return it to her.
• Zebenar Kinest (vnum 3766): Exploration task to Arannia's shop in Var Bandor.
• Qilmil (1316): Dead drop task, taking an offering to an Elar shrine (Lithling freehold).
• Rehaeda (vnum 21928): Mass kill task (young srryn in Jasa lake).
• A huge black dog (vnum 19155): Collection task (1x bacon from Nika in Inessa).
• The remains of a priest (vnum 8104): Autocompleting inverse bit-flip task with bit reward.