タイマーにテキスト、プロセスバーなどを表示するコンポーネントを提供するプラグイン – SRCrazy_TimerDisplay.js

タイトル
Provides a component that displays a timer with text, progreess bar, etc...============================================================================
作者名
ヘルプ
============================================================================
S_Rank_Crazy's Timer Display Plugin
============================================================================
This plugin provides a timer display that can be customised either through
the Plugin Manager, or when created through a Script Call.

If you're using the MVCommons or PluginManagement plugins then any dependency
issues will be output as errors when the game loads.

All SRCrazy plugins are rename safe - you can rename the file and it'll still
work. All parameters and commands are case-safe (no need to worry about
case-sensitive input) unless specifically stated. This doesn't include
Comment Tags or file names/paths; they are still case sensitive.

MVCommons supported but not required for use.

============================================================================
USAGE

The TimerDisplay can be set up in the Plugin Manager to be configured in
many different ways, which allows for script calls to be relatively easy to
implement in the Event Editor for displays that are consistent in their
appearance and/or behaviour. However, if you need to have different "types"
of displays you have all of the same configuration settings available to
you for the creation of each individual TimerDisplay.


-----------------
Creating Timers
-----------------

The plugin can be accessed through the SRCrazy global namespace at:

SRCrazy.Plugins.TimerDisplay

The plugin has a `construct` method which can be used to create a timer
by supplying a descriptor to the function call:

SRCrazy.Plugins.TimerDisplay.construct({ duration: 10 });

The above call will create a TimeDisplay with the default settings that will
be removed after 10 seconds. The descriptor can contain a number of different
options which will customise how it looks and behaves. If any of the options
are omitted, the plugin's defaults (as found in the Plugin Manager) will be
used.

Here's a list of all of the options that can be used:

name - The name of the TimerDisplay, can be used to destroy the timer at a
later point
duration - The amount of time (or number of frames) to run the timer for
useFrames - Indicates whether the timer uses seconds (real time) or frames

x - The position of the TimerDisplay on the x-axis
y - The position of the TimerDisplay on the y-axis
width - The width of the TimerDisplay
height - The height of the TimerDisplay

switchId - Triggers the switch when the timer completes. If the switch is
on, switch is turned off and vice versa.
variableId - Sets the current progress of the timer in the specified
variable
commonEventId - Triggers a Common Event when the timer completes

showWindow - Indicates whether hte display shows a Window
showBar - Indicates whether the display shows a timer bar

barX - The position of the bar on the x-axis
barY - The position of the bar on the y-axis
barWidth - The width of the bar
barHeight - The height of the bar
barColour1 - The colour used for the left side of the bar
barColour2 - The colour used for the right side of the bar
barColourBg - The colour used for the background of the bar

showBackgroundImage - Indicates whether an image is to be displayed behind
the bar
backroundImage - The path to the image to display

showForegroundImage - Indicates whether an image is to be displayed in front
of the bar
foregroundImage - The path to the image to display


----------------------------
Creation through Shorthand
----------------------------

1. The Shorthand Function

The plugin provides a customisable function that is made available in the
global scope of the window. In short, you can (re)name a function and decide
what it's parameters are (from a support list, see below) and then use that
function in a Script Call to create TimerDisplays more easily.

By default the Shorthand Function (SHF) is set up to be:
timedbar(x, y, duration, useFrames);

`timedbar` is the name of the function, and the function's parameters are
set to be `x, y, duration, useFrames`. To use this default set-up, use the
following in a Script Call:

timedbar(10, 10, 5, false);

The above example will display a window at position [10,10] and will be
removed after 5 seconds. Passing true or to the `useFrames` parameter will
translate the `duration` value as the number of frames to count. If any
parameters are omitted then their values will default to the values
specified in the Plugin Manager.

Additional methods can be called once the timedbar function has been called
in order to update a variable, switch or trigger an event. These methods are:

assignToVariable(variableId);
This sets the current progress of the bar the specified variable

assignToSwitch(switchId);
This flips a switch when timer is complete. If the switch is on, switch is
turned off and vice versa.

assignToCommonEvent(commonEventId);
This calls a Common Event when the timer is complete.

These methods can be chained in order to use a combination of them.

Eg:
timedbar(10, 10, 5).assignToVariable(1).assignToSwitch(1);

This will create the display as before but also update variable with ID 1
every frame, and then change switch with ID 1 when complete.



2.Shorthand Function Parameters

The SHF's parameters don't always have to be `x, y, duration, useFrames`,
you can customise what properties you want to control and in which order they
are passed in to the SHF. For exmaple, if you wanted to only ever set the
duration and the colour(s) use for the bar when calling the SHF you can set it
up to look like this:

timedbar(duration, barColour1, barColour2);

For a full list of the supported values for the "Shorthand function parameters"
parameter in the Plugin Manager, see the above section on "Creating Timers".


-----------------
Managing Timers
-----------------

If the timer is provided with a name upon creation, it can be manually
managed through other Script Calls to pause/unpause and destroy it...

SRCrazy.Plugins.TimerDisplay.pause(timerName, hide);
This pauses the named timer (if found), and optionally hides it.

SRCrazy.Plugins.TimerDisplay.unpause(timerName, show);
This unpauses the named timer (if found), and optionally shows it.

SRCrazy.Plugins.TimerDisplay.destroy(timerName);
This destroys the named timer (if found).

Similarly to the Shorthand function (see above), these three methods can
also been added to the global scope to make calling them less cumbersome.
These are also set up in the SCRIPT CALL section of the Plugin PArameters
section of the Plugin Manager.

============================================================================
TERMS OF USE

Free for commercial and non-commercial use. No credit need be given, but
always appreciated.

============================================================================
COMPATIBILITY

Requires SRCrazy_Core and SRCrazy_Timer plugins.

============================================================================
パラメータ
param debug
desc Enables logging for this plugin to the debug console.
default false

param

param -- SCRIPT CALL --
desc Parameters in this section relate to script calls

param Global pause function
desc Adds a function for pausing a timer to the global scope with the specified name
default pauseTimer

param Global unpause function
desc Adds a function for unpausing a timer to the global scope with the specified name
default unpauseTimer

param Global destroy function
desc Adds a function for destroying a timer to the global scope with the specified name
default destroyTimer

param Global check function
desc Adds a function for checking the existence of a timer to the global scope with the specified name
default doesTimerExist

param

param Shorthand function
desc Adds a function to the global scope with the specified name
default timedbar

param Shorthand function parameters
desc These are the parameters that will be passed in to the shorthand function. See the help section for more info.
default x, y, duration, useFrames

param

param -- TIME TRACKING --
desc Parameters in this section relate to how time is tracked by the timers.

param Duration
desc The default duration of timers
default 1

param Use frames
desc Indicates whether timers use frame or real time measurements by default
default false

param

param -- DISPLAY: GENERAL --
desc Parameters in this section relate to the default display of timers.

param Default position
desc The position of the display, formatted as: x y
default 10 10

param Default size
desc The dimensions of the display, formatted as: width height
default 200 50

param Show window
desc Indicates whether a window is shown in the display by default
default true

param

param -- DISPLAY: BAR --
desc Parameters in this section relate to the default state of the timer bar in the display.

param Show bar
desc Indicates whether a bar shown in the display by default
default true

param Bar position
desc The position of the bar, formatted as: x y
default 10 15

param Bar size
desc The dimensions of the bar, formatted as: width height
default 180 20

param Bar background colour
default transparent

param Bar left colour
default #ff0000

param Bar right colour
default #ff9900

param

param -- DISPLAY: IMAGES --
desc Parameters in this section relate to images in the display.

param Show background image
desc Indicates whether an image is shown in the display, behind the bar
default false

param Background image
desc The path to the image relative to the img folder
default parallaxes/BlueSky

param Show foreground image
desc Indicates whether an image is shown in the display, in front of the bar
default false

param Foreground image
desc The path to the image relative to the img folder
default parallaxes/BlueSky

ライセンス表記
are omitted, the plugin's defaults (as found in the Plugin Manager) will be
parameters are omitted then their values will default to the values
Free for commercial and non-commercial use. No credit need be given, but

紹介ページ https://github.com/agent-bizzle/rmmv-plugins/blob/master/src/SRCrazy_TimerDisplay.js