Documentation for smoke.lic

Smoke Image Trainer - User Guide

What This Script Does

smoke.lic automates the practice and mastery of smoke images in DragonRealms. Smoke images are a recreational skill where players inhale from a lit cigar or pipe and exhale smoke shaped into artistic forms -- deer, dragons, ships, and dozens of others.

The script handles the full workflow: retrieving your smoking implement, lighting it, cycling through images (inhale/exhale), relighting when tobacco runs out, tracking which images you have mastered, and optionally teaching or learning images with another player.

---

Prerequisites

Before using this script you need:

1. A smoking implement -- either a pipe or cigars (or both).
2. Tobacco -- if using a pipe, you need loose tobacco in your container.
3. A way to light it -- one of:
   • Being a Warrior Mage (the script casts Cantrip > Beginner > Targeted to light).
   • A lighter item (e.g., a lava drake lighter).
   • Flint and steel plus a bladed weapon (fallback method).
4. A container to hold your pipe, tobacco, lighter, etc.
5. At least one known smoke image -- you learn your first images from another player or at events.

---

YAML Configuration

Add a smoke: block to your character's YAML settings. Here is a full example with every supported option:

smoke:
  container: smoking jacket           # Container holding pipe, tobacco, lighter, cigars
  pipe: glitvire pipe                 # Noun/adjective of your pipe (if using a pipe)
  lighter: lava drake                 # Noun/adjective of your lighter item (optional)
  lighter_tied_to: belt               # If your lighter is tied to something (optional)
  blade: serrated parazonium          # Blade for flint-and-steel lighting (optional)
  time_between_exhales: 3             # Seconds to pause between exhales (default: 1)
  clean_list_of_mastered: true        # Skip images you have already mastered (true/false)
  smoke_room: 1234                    # Room number to walk to before smoking (optional)
  smoke_images:                       # Curated list of images to practice (optional)
    - deer
    - tart
    - dragon

Setting Details

Setting	Required	Description
container	Yes	The container that holds your pipe, tobacco, lighter, and/or cigars.
pipe	If using pipe	The noun (with optional adjective) of your pipe.
lighter	No	A lighter item. If absent and you are not a Warrior Mage, the script falls back to flint and steel.
lighter_tied_to	No	If your lighter is tied to a belt, pouch, etc., set this so the script unties/reties it instead of getting/putting it.
blade	No	A bladed weapon registered in your EquipmentManager, needed for the flint-and-steel lighting method.
time_between_exhales	No	Delay in seconds between each inhale/exhale cycle. Defaults to 1. Increase if you want a more relaxed pace.
clean_list_of_mastered	No	When true, the script automatically removes images you have fully mastered from the practice rotation.
smoke_room	No	A room ID to walk to before beginning. Useful if you want to practice in a specific location.
smoke_images	No	A curated list of image names to practice. If omitted, the script practices all your known images.

---

Commands and Usage

The script supports several distinct modes of operation, selected by the arguments you pass.

Practicing with a Pipe

;smoke pipe
;smoke pipe deer
;smoke pipe 5
;smoke pipe until_out
;smoke pipe deer 3

• pipe -- tells the script to use the pipe defined in your YAML.
• An image name (e.g., deer) -- practice only that specific image.
• A number (e.g., 5) -- smoke through 5 pieces of tobacco before stopping.
• until_out -- keep smoking until you run out of tobacco entirely.

When no image is specified, the script randomly selects from your eligible image list each exhale.

Practicing with a Cigar

;smoke cigar
;smoke slim cigar
;smoke twisted black cigar deer
;smoke cigar 10
;smoke cigar until_out

• Provide the cigar's noun (e.g., cigar, slim cigar, twisted black cigar).
• Image name, repeat count, and until_out work the same as with pipes.

Light Only

;smoke pipe light_only
;smoke cigar light_only

Lights your pipe or cigar and exits immediately. Useful when you want to smoke manually but automate the lighting process (especially the multi-step flint-and-steel method).

Reset Known Images

;smoke reset_known

Resets your tracked image lists. Use this after you have learned new images (from a teacher or an event) so the script can rediscover what you know. The script will:

1. Clear its internal list of your known images.
2. Clear its internal list of your mastered images.
3. Run smoke list in-game to rebuild both lists from scratch.
4. Print out which images still need training.

Teaching an Image

;smoke teach pipe Mahtra
;smoke teach pipe Mahtra deer
;smoke teach cigar Mahtra wolf

Teaches smoke images to another player. Requirements:

• You must have mastered the image you want to teach.
• Both you and the student must be holding lit smoking implements.
• The student must be running the learn counterpart (see below).

If you specify an image name, only that image is taught. If you omit it, the script teaches all images from your smoke_images YAML list.

The script handles the full teaching loop: it offers the lesson, waits for the student to pay attention, demonstrates the image, waits for the student to attempt it, and repeats until the student learns.

Learning an Image

;smoke learn pipe Mahtra
;smoke learn cigar Mahtra

Learns smoke images from a teacher. The script:

1. Listens to the teacher.
2. Waits for the teacher to demonstrate.
3. Attempts the image.
4. Repeats until learned, then moves on to the next image the teacher offers.

The learner does not specify an image name -- the teacher controls what is taught.

---

Available Smoke Images

There are currently 34 known smoke images in the game:

Standard Images	Special/Event Images
deer	web
dragon	phoenix
rabbit	bracelet
pixie	skeleton
kitten	tart
troll	almanac
horse	dartboard
paladin	wolf
whip	vine
cloak	forge
stump	moongate
fleas	mage
daisies	violin
unicorn	altar
rams	trader
bandit
ship
grave
fish

Special images were introduced at Guildfest events and through other in-game activities. You must learn each image from a player who has already mastered it (or learn it at an event).

---

Mastery Progression

Each image progresses through 6 quality levels as you practice. Olvi (Halflings) use a unique set of tier names and skip the first level, starting directly at level 2. All other races begin at level 1 (Learning). The final Master tier is shared by all races.

Level	Olvi (Halfling)	Other Races
1	--	Learning
2	Wheezer	Beginner
3	Sneezer	Amateur
4	Whiffler	Adequate
5	Streamer	Competent
6	Master	Master

When you reach Master level on an image, it is marked with an asterisk (*) on your smoke list. If clean_list_of_mastered is enabled, the script automatically removes mastered images from your practice rotation so you focus on images that still need work.

---

Lighting Methods

The script attempts to light your tobacco in this priority order:

1. Warrior Mage cantrip -- If your character is a Warrior Mage, the script prepares and gestures a fire cantrip (prep c b t / gesture). No extra items needed.
2. Lighter -- If you have a lighter set in your YAML, the script retrieves it (or unties it) and points it at the tobacco. After lighting, it stows (or reties) the lighter.
3. Flint and steel -- The fallback. The script gets flint from your inventory, lowers the smoking item, draws your configured blade, and strikes. This requires blade to be set in YAML and registered in your EquipmentManager.

If a method fails (lighter not found, etc.), the script falls back to the next method automatically.

---

Tracking and State

The script uses UserVars to persist state between sessions:

• UserVars.smoke_images_known -- The list of images your character knows. Built from smoke list.
• UserVars.smoke_images_mastered -- The list of images your character has fully mastered.

These variables survive script restarts. If they get out of sync (e.g., after learning new images), run ;smoke reset_known to rebuild them.

---

Workflow Example

A typical session:

1. Set up your YAML with container, pipe/cigar, and lighter.
2. Run ;smoke pipe to practice all known images.
3. The script walks to your smoke_room (if set), lights your pipe, and begins cycling through images.
4. When tobacco burns out, it automatically reloads and relights.
5. Mastered images are removed from the rotation (if clean_list_of_mastered is enabled).
6. When finished, the script stows your pipe and reports completion.

---

Troubleshooting

Problem	Solution
Script exits immediately	Make sure your container, pipe/cigar noun, and lighter noun exactly match your in-game items.
"Missing flint" message	Buy flint from a general store. Every adventurer should carry some.
Images not updating after learning	Run ;smoke reset_known to rebuild your image lists.
"Student Unresponsive" during teach	The student needs to be in the same room and listening. Ensure they run ;smoke learn first.
Script does not stow cigar at end	This is a known limitation; the script only auto-stows pipes. Stow your cigar manually.
"No valid images selected"	Your curated list may only contain mastered images. Remove them from smoke_images in YAML or disable clean_list_of_mastered.
"Teaching borked"	Wait and try the teach/learn session again. The game may have timed out the session.