Help.txt

Dice in the Vineyard

Dice in the Vineyard is a dice tracker for Dogs in the Vineyard.  It creates
poker-chip-styled tokens for each roll and stacks them on the tabletop in areas
set aside for each character.  During play, players can spend roll tokens, roll
in additional tokens, and request chip counts for any character in play.

It is recommended that this script be used in conjunction with the CommandShell
module, which will improve output formatting and command discovery.


Using Dice in the Vineyard:

Before using Dice in the Vineyard, it is recommended that image URLs be set for
each chip value.  These can be set in the script in the DEFAULT_URLS dictionary
or within the game via the "setimage" subcommand (described below).  For best
results, use a PNG with transparency, so that chips will stack appropriately.
You may wish to set the CHIP_HEIGHT parameter, which defines the height, in
pixels, of the side of the chip (i.e. additional chips will be placed this many
pixels above the chip beneath them in order to create a stacking effect).  Any
chip without a specific image set will use GENERIC_URL and will use a status
icon to display its value.

Each character to be tracked must have space allocated on the tabletop for its
chips.  This can be accomplished via the "add" subcommand, which will allocate
an area starting at the specified square and extending six squares right and
four squares down (this can be altered by changing the values of BOX_WIDTH and
BOX_HEIGHT, but should always be at least two wide and a multiple of two tall,
and should have a total area of at least 24 squares).  A 2x2 area in the top
left will be reserved for the character token and for chip tokens to be played;
ten 1x2 areas will be used for stacking chips of each value 1-10.


Commands:

All Dice in the Vineyard commands are accessed via the "ditv" command, which
provides the following subcommands:

    !ditv help
	Display a help message listing the various subcommands.
    !ditv add NAME X Y [COLOR]
	Allocate an area on the tabletop for a character with the given name.
	X and Y are given in squares, starting at 0,0 in the top left.
	If COLOR is provided, it should be an HTML-style RGB string (e.g.
	"#60A0FF"), which will be used to border the area (default is #FFFF00).
    !ditv remove NAME
	Remove the specified character and all its chips, and free its space
	on the tabletop.
    !ditv clear NAME
	Remove all chips from the specified character.
    !ditv roll NAME DICE
	Roll DICE (e.g. "3d4+1d6") and add to the specified character's chips.
	Dice specifications must be of the form XdY, and can be separated by
	whitespace or "+".
    !ditv count NAME
	Display a count of the specified character's chips in global chat.
    !ditv setimage VALUE [URL]
	Set the image URL for the specified chip value.  If URL is not given,
	the currently selected token's image will be used.
    !ditv images
	Display a table of all chip images, including the default image which
	will be substituted in for any chip value without a defined image.