HomeSoul v1.0.0
Last updated: 8/15/2026
Part of the HomeSuiteHome suite by Blodwedd Mallory
===============================================================================

QUICK START
-----------
1. Mark tab: name your mark, choose a type (Emote, Toy, Consumable, or Chain).
2. Set your timing mode (Loop, Timer, or Once).
3. Click Start Mark, walk to the spot in your house, click Place Here.
4. Soul tab: your mark is live. Pause, clone, or delete any time.


MARK TYPES
----------
EMOTE MARKS — gold square on the Soul tab.
Choose an emote from the dropdown (sleep, drink, dance, etc.). Fires
automatically when you walk into the mark radius.

TOY MARKS — green square on the Soul tab.
Choose a toy from your collection. On zone entry a prompt appears:
Use [Toy Name]? Click Yes to fire it. WoW requires a direct player
click for toy use — HomeSoul cannot fire toys automatically.
The prompt auto-dismisses in 30s and is suppressed if the toy is
on cooldown.

CONSUMABLE MARKS — blue square on the Soul tab.
Like toy marks, but for food, drinks, and other usable items.
Prompts on zone entry the same way toy marks do.

CHAIN MARKS — purple square on the Soul tab.
A sequence of emotes, toys, or consumables with configurable delays
between each step. Use chains for complex multi-action sequences
like a full meal routine or an arrival ritual.


TIMING MODES
------------
LOOP    Holds one pose continuously — sleeping in a bed, sitting in a chair.
        Fires every 30 seconds while you stay in the zone.

TIMER   Repeats on a clock — fires N times, X seconds apart, then stops
        until next zone entry. Use for multi-emote bursts.

ONCE    Fires once per zone visit. Re-triggers each time you leave and
        re-enter the zone radius.


AREAS TAB — YOUR HOUSE'S ROOMS
--------------------------------
Areas define the rooms of your house. Marks are grouped by area in the
Soul tab, and zones live inside areas.

Adding an area: type a name and click Add, or stand in the room you want
and click Capture to create it instantly using Blizzard's own name for
that room type (rename it any time). If two rooms share the same shape,
Capture numbers them automatically ("Square Room (Small) 2") so they
never collide.

Editing an area: click Edit, then Capture This Room while standing in
that room to (re)capture which room it's tied to — useful for areas
created before this feature existed, or to point an area at a different
room.

Areas show a subnote under each area name:
  "No room captured"
  "Entry" / "Square Room (Small)" / etc. — Blizzard's name for that room

Delete: clicking Delete shows a Sure? confirmation before removing the area.
  Deleting an area is permanent — zones assigned to it revert to Freestanding
  and marks lose their area assignment.

Areas are scoped to the house where they were created. Switching houses
shows only that house's areas and zones.


ROOM-AWARE MARK FIRING
------------------------
Marks check which room you're actually in, not just distance — so a mark
in one room won't fire if you're standing in a different room stacked
directly above or below it (like a stairwell).

New marks and Move & Re-place both capture this automatically. Marks
placed before this existed keep firing on distance alone until you
Move & Re-place them (see SOUL TAB below), which also picks up their room.


ZONES TAB — SUB-REGIONS
------------------------
Zones let you name and map sub-regions inside your house — a dance floor,
a quiet corner, the bar. Each zone belongs to a parent area.

Adding a zone: type a name and click Add, then click Edit to draw its
boundary and assign a parent area.

Drawing a boundary:
  Polygon — walk each corner of the room and click Add Point (minimum 3),
             then click Close Polygon.
  Radius  — stand at the zone center, click Set Center. Walk to the
             nearest edge, click Set Edge Point. Click Save.
Drawing a boundary while standing in a room you've already captured as
an Area automatically assigns that Area as the zone's parent.

Pause/enable: the checkbox pauses a zone without deleting it. A paused zone
dims in the list and its boundary is inactive.

Delete: clicking Delete shows a Sure? confirmation before the zone is removed.

Note: zone triggers — ambient effects for any player with the HomeSoul
addon who enters — are coming soon. Boundaries set now will activate
automatically when the feature ships.


SOUL TAB — MANAGING YOUR MARKS
-------------------------------
The Soul tab is your mark list, organized by area. Each row shows the
mark name, type swatch, and timing mode.

Checkbox:  Pause a mark without deleting it. Paused marks stay saved
           but won't fire until re-enabled.

Edit:      Opens the mark form to change name, type, timing, or area.

Clone:     Duplicates a mark. Re-place it at a new location.

Del:       Permanently removes the mark.

Move & Re-place: Moves the mark's trigger position to your current location.
           Use this if a mark stops firing after moving furniture or if the
           mark was placed in a different housing session.


FLAVOR TEXT
-----------
Optional /me text that fires alongside the mark trigger.
Works for emote, toy, and consumable marks.
By default fires once per zone entry even if Fires > 1.
Check Repeat to send flavor text with every fire in a burst.


TOY PICKER
----------
Favorites Only (Options tab): shows only toys you have starred in
your Toy Box.
If the list is empty: open your Toy Box, star the toys you want,
then re-open the picker. Uncheck Favorites Only to see all.

CONSUMABLE PICKER
-----------------
Shows items currently in your bags. If a consumable mark fires and
the item is not in your inventory, the prompt will still appear but
the item cannot be used.


OPTIONS TAB
-----------
Enable HomeSoul: uncheck to pause all mark firing without disabling
the addon. Marks are preserved; re-check to resume.

Show minimap button: uncheck to hide the HomeSoul icon from your
minimap. Use /homesoul or /hs to open the window if the button
is hidden.

Mark cooldown (minutes): how long Once and Timer marks rest before
they can fire again (default: 60). Loop marks ignore this setting.

Toy Options — Favorites only: the toy picker shows only toys you
have starred in your Toy Box. See TOY PICKER above for more.

Missing Emotes: HomeSoul includes a full list of current emotes.
If one is missing, type its token in the box (e.g., /cry) and
press Enter to add it to your list.

Danger Zone: type RESET and click the button to reset all marks,
zones, and areas back to a fresh install (areas return to the 8
default names). Your settings above are not affected. This cannot
be undone.


TROUBLESHOOTING
---------------
Marks not firing:
  Confirm you are in your own home instance. HomeSoul only fires
  marks when you are the housing owner.

Toy or consumable prompt doesn't appear:
  Check that the mark is enabled and that you entered the zone radius.

Mark not firing after re-entry:
  ONCE marks rest for the cooldown period (default 60 min). Editing
  and saving the mark resets it.

Toy picker is empty:
  Toy data may not be cached yet. Try /reload and check again after
  a few seconds.

Red "MAP MISMATCH" label on Soul tab:
  A mark's saved position doesn't match your house's internal map ID
  this session. Fix: Edit the mark, then Move & Re-place it to recapture
  its location.

Areas, zones, or marks showing up in the wrong house:
  Areas and marks created before house-scoping was added may not know
  which house they belong to yet, so they show up in every house until
  told. Fix: stand in the correct house, go to the Areas tab, click Edit
  on the area, then click Done (no changes needed) -- this tells HomeSoul
  which house it's in. If an individual mark still shows up in the wrong
  house afterward, do the same from the Soul tab: Edit, then Save Changes.


COMING SOON
-----------
Guest broadcasting -- marks and flavor text visible to visitors in your
home, not just the owner.

Zone triggers -- zones will fire ambient effects for any player with the
HomeSoul addon who enters. Draw your boundaries now; detection activates
automatically when the feature ships.
