Add script to generate and display animations

Animation/Help.txt

@@ -0,0 +1,276 @@
+Animation
+
+Animation allows the user to define and run animations consisting of images from
+a Roll20 user library.  Each frame's duration, position, and orientation can be
+set independently of the other frames, as can aura and light properties.
+
+It is recommended that this script be used in conjunction with the CommandShell
+module, which will improve output formatting and command discovery.
+
+
+Commands:
+
+All Animation commands are accessed via the "anim" command, which provides the
+following subcommands (each described in greater detail in its own section):
+
+    !anim help [COMMAND]
+	Display a help message.  If COMMAND is specified, the help message will
+	detail the usage of the specified subcommand.  Otherwise, the help
+	message will summarize all available subcommands.
+
+    !anim add TYPE [...]
+	Add/name a new image, animation, or frame (as determined by TYPE).  See
+	"!anim add" section below for full subcommand details.
+
+    !anim edit TYPE [...]
+	Edit an existing image, animation, or frame (as determined by TYPE). See
+	"!anim edit" section below for full subcommand details.
+
+    !anim remove TYPE [...]
+	Remove an existing image, animation, or frame (as determined by TYPE).
+	See "!anim remove" section below for full subcommand details.
+
+    !anim list TYPE [...]
+	Display information about existing images, animations, or frames (as
+	determined by TYPE).  See "!anim list" section below for full subcommand
+	details.
+
+    !anim run NAME [options]
+	Run a specified animation.  See "!anim run" section below for full
+	subcommand details.
+
+
+Subcommand Reference:
+
+The "!anim add" subcommand operates in three modes:
+
+    !anim add image NAME [URL]
+	Names the specified image for later reference.  If URL is not provided,
+	the image for the currently selected token will be used.  In either
+	case, the relevant image must come from a Roll20 user library.
+
+    !anim add animation NAME [CYCLES]
+	Creates an empty animation.  If CYCLES is specified, it is the default
+	number of times to cycle through the animation when it is played.  If
+	not, the default is 1.
+
+    !anim add frame ANIMATION IMAGE DURATION [options]
+	Adds a frame to the specified animation.  IMAGE can be either a URL or
+	the name of an image defined with "!anim add image".  DURATION is the
+	amount of time (in milliseconds) that the frame will be displayed when
+	the animation is run.
+
+The "!anim add frame" subcommand accepts the following options:
+
+    -x X, -y Y		Frame offset (in pixels) from the animation origin
+			(default: 0, i.e. centered at animation center)
+
+    -w W, --width W	Frame width in pixels (default: 70, i.e. 1 square)
+    -h H, --height H	Frame height in pixels (default: 70, i.e. 1 square)
+
+    -r A, --rotation A	Frame rotation in degrees, relative to the animation's
+			orientation (default: 0, i.e. aligned with animation)
+
+    -a R, --aura R	Radius (in page units) of frame's aura (default: none)
+    --auracolor C	Color of frame's aura (default: #FFFF99)
+    --aurasquare	Make frame's aura square (default: circle)
+
+    -t C, --tint C	Color tint to be applied to frame (default: none)
+
+    -l R, --light R	Radius (in page units) of light emitted by frame
+			(default: none)
+    -d R, --dim R	Radius (in page units) at which frame's light begins to
+			dim (default: none)
+    --lightangle A	Angle (in degrees) of light emitted by frame
+			(default: 360)
+
+    -i I, --insert I	Index (0-based) at which to insert new frame
+			(default: after last frame)
+
+    -C I, --copy I	Index (0-based) of frame to copy.  Any arguments which
+			set frame properties will override the copied properties
+			(for example, spinning an image can be accomplished by
+			creating a first frame, then repeatedly calling
+			"!anim add frame ANIMATION -C -1 -r A", where A is
+			a number which is increased or decreased with each
+			call).  If I is negative, it is relative to the
+			insertion index (so "-C -1" will copy the frame just
+			before the new frame).  In this form of the command, the
+			IMAGE and DURATION arguments are optional.
+
+    -I IMG, --image IMG	As IMAGE argument, for use with --copy.
+    -D T, --duration T	As DURATION argument, for use with --copy.
+
+
+The "!anim edit" subcommand operates in three modes:
+
+    !anim edit image NAME [URL]
+	Replaces the specified named image with a new image.  If URL is not
+	provided, the image for the currently selected token will be used.  In
+	either case, the relevant image must come from a Roll20 user library.
+
+    !anim edit animation NAME CYCLES
+	Sets the default number of times to cycle through the specified
+	animation when it is played.
+
+    !anim edit frame ANIMATION FRAME_INDEX [options]
+	Modifies a frame of the specified animation.  FRAME_INDEX is the 0-based
+	index of the frame to modify.
+
+The "!anim edit frame" subcommand accepts the following options:
+
+    -x X, -y Y		Frame offset (in pixels) from the animation origin
+
+    -w W, --width W	Frame width in pixels
+    -h H, --height H	Frame height in pixels
+
+    -r A, --rotation A	Frame rotation in degrees, relative to the animation's
+			orientation
+
+    -a R, --aura R	Radius (in page units) of frame's aura
+    --auracolor C	Color of frame's aura
+    --aurasquare	Make frame's aura square
+
+    -t C, --tint C	Color tint to be applied to frame
+
+    -l R, --light R	Radius (in page units) of light emitted by frame
+    -d R, --dim R	Radius (in page units) at which frame's light begins to
+			dim
+    --lightangle A	Angle (in degrees) of light emitted by frame
+
+    -I IMG, --image IMG	Name or URL of frame image
+
+    -D T, --duration T	Number of milliseconds to show frame
+
+
+The "!anim remove" subcommand operates in three modes:
+
+    !anim remove image NAME
+	Removes the specified image.
+
+    !anim remove animation NAME
+	Removes the specified animation.
+
+    !anim remove frame ANIMATION FRAME_INDEX
+	Removes a frame from the specified animation.  FRAME_INDEX is the
+	0-based index of the frame to remove.
+
+
+The "!anim list" subcommand operates in three modes:
+
+    !anim list image [NAME]
+	If NAME is provided, will display the URL of the specified image.
+	Otherwise, will list the names of all named images.
+
+    !anim list animation [NAME]
+	If NAME is provided, will display summary info about the specified
+	animation.  Otherwise, will list the name and duration of each stored
+	animation.
+
+    !anim list frame ANIMATION [FRAME_INDEX]
+	If FRAME_INDEX is provided, will display all properties of the specified
+	frame of the specified animation.  Otherwise, will list all the frames
+	of the specified animation.
+
+
+The "!anim run" command displays an animation:
+
+    !anim run NAME [options]
+
+The "!anim run" subcommand accepts the following options:
+
+    -x X, -y Y		Coordinates (in pixels) at which to display the
+			specified animation.  If either is not specified, the
+			corresponding coordinate of the currently selected
+			token will be used.  If no token is used, the midpoint
+			of the page will be used.
+
+    -r A, --rotation A	Rotation (in degrees) at which to display the animation
+			(default: 0, i.e. do not rotate)
+
+    -f F, --timefactor F    Scale factor for frame durations (default: 1)
+
+    --xscale F		Size scale factor in the X direction, affecting frame
+			sizes, offsets, aura radii, and light radii (default: 1)
+    --yscale F		Size scale factor in the Y direction, affecting frame
+			sizes, offsets, aura radii, and light radii (default: 1)
+			Aura and light radii use the average of the X and Y
+			scale factors.
+
+    --cycles N		Number of times to run through animation frames.
+			Overrides the animation's cycles setting.
+
+    -p ID, --page ID	ID of the page on which to display the animation
+    -P, --playerpage	Display animation on page with player ribbon.
+			If no page is specified, the page containing the
+			currently selected token will be used.  If no token is
+			selected, the page with the player ribbon will be used.
+
+
+Examples:
+
+!anim add image HighDensityFire
+    With a token selected, will name the token's image "HighDensityFire" for
+    later reference.
+
+!anim add animation Fireball
+    Will create an empty animation named "Fireball"
+
+!anim add frame Fireball HighDensityFire 50 -w 35 -h 35 --light 10 -dim 5
+    Will create a 35x35 (half-square) frame using the "HighDensityFire" image.
+    The frame will last for 50ms (1/20th of a second), and will emit 5 feet
+    (1 square) of bright light and 5 further feet of dim light.
+
+!anim add frame Fireball --copy 0 --rotation 10 -w 70 -h 70 -l 20 -d 10
+    Will create a 70x70 (full-square) frame using the first frame as a template.
+    The new frame will be rotated 10 degrees clockwise, and will have both its
+    size and light radius doubled.
+
+!anim add frame Fireball -C -1 -I MidDensityFire -r 20 -w 140 -h 140 -l 40 -d 20
+    Will create another, larger frame, using the second frame as a template.
+    This one will use a different image, will be rotated a further 10 degrees
+    clockwise, and will have both its size and light radius doubled again.
+
+!anim edit frame Fireball 2 -I HighDensityFire
+    If we decide the third frame was too early to switch to the "MidDensityFire"
+    image, this command will change its image to "HighDensityFire".
+
+!anim edit HighDensityFire http://...
+    Will change the "HighDensityFire" image to the new image.  Note that this
+    will not affect existing frames using the "HighDensityFire" image; they will
+    continue to use whatever that name pointed at when they were defined.
+
+!anim remove frame Fireball 17
+    Remove the 18th frame of the "Fireball" animation.
+
+!anim list image
+    Will whisper a list of currently defined images, in alphabetical order, to
+    the user who executed the command.
+
+!anim list image HighDensityFire
+    Will whisper the URL of "HighDensityFire" to the user who executed the
+    command, displaying the image in the whisper.
+
+!anim list animation
+    Will whisper a list of currently defined animations, in alphabetical order,
+    to the user who executed the command.
+
+!anim list animation Spinner
+    Will whisper information about the specified animation to the user who
+    executed the command.
+
+!anim list frame Fireball
+    Will whisper a list of frames in the "Fireball" animation to the user who
+    executed the command.
+
+!anim list frame Fireball 0
+    Will whisper all the properties of the first frame of "Fireball" to the
+    user who executed the command
+
+!anim run Fireball
+    With a token selected, will run the "Fireball" animation centered on the
+    selected token.
+
+!anim run Fireball -f 5 -x 500 -y 350 --xscale 2 --yscale 2
+    Will run the "Fireball" animation centered at (500,350), doubled in size
+    and running in slow-motion (taking five times as long to run).