特定の場所または地域でマークされたランダムな点で事前作成イベントを生成するプラグイン – YEP_EventSpawner.js

============================================================================
Introduction
============================================================================

WARNING: This plugin is best used with RPG Maker MV 1.5.0 or above! This is
because the MV 1.5.0 editor allows for this plugin to be made in an orderly
and efficient manner. Please make sure your RPG Maker MV software is up to
date before using this plugin to make the most out of it.

While in RPG Maker MV, there's the ability to make events hidden and reveal
themselves to make it look like they've spawned out of nothing. However,
there isn't an innate function to actually spawn an event from nothing. This
plugin will provide users the ability to actually spawn an event that is
premade and ready from another map(s).

A spawned event will contain all the data from its original source, from the
event's page conditions to the event commands to the graphical settings. And
should the original source be updated in the future, the spawned event will
update as well. Spawned events can also be preserved and remain on the map
if the player reenters the map or reloads a save.

More information will be explained in the Instructions section of this
plugin's help file.

============================================================================
Instructions
============================================================================

Use the plugin parameter 'Template Maps' to select which maps your game will
preload maps from. These maps will contain the events that you want other
events to spawn as. Any kind of event can be used as a spawn template, from
trigger events to auto run events to parallel events.

If you are using RPG Maker MV 1.5.0+ and wish to make use of template names,
add them through the 'Template Names' plugin parameter. The data from the
Template Names parameters can be changed and all events in-game that use
script calls with the respective Template Name will be updated accordingly.

--------------------
Spawning Limitations
--------------------

However, there are some rules that must be applied before an event can be
spawned at a desired location. They are as follows:

1. The spawn location must not be occupied by another event, even if the
event is of a different priority level. This is to prevent overstacking
and causing problems for the RPG Maker MV engine.

2. The spawn location cannot have a vehicle present. This is to prevent
priority conflicts with the event when triggered.

3. The spawn location must exist on the map. It cannot have coordinates
that are outside of the map's boundaries.

As long as these rules are followed, the event will spawn properly provided
you follow the format used for the Script Calls listed in the section below.

============================================================================
Script Calls
============================================================================

To spawn events into your maps, use the following script calls:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Spawn Event - Script Calls
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

This will spawn a new event using the information from 'mapId' 'eventId'
as its base. The new event's ID will start at 1001 (or whatever you've
set the plugin parameter 'ID Starting Range' to) and onward.

- - -

Yanfly.SpawnEventAt(mapId, eventId, x, y, preserved)
- This will spawn the desired event into the specific coordinates.
- Replace 'mapId' with the ID of the map with the event to morph into.
- Replace 'eventId' with the ID of the event to morph the target into.
- Replace 'x' with the X position on the map to spawn the event at.
- Replace 'y' with the Y position on the map to spawn the event at.
- The X and Y positions MUST NOT have an event present at that location.
- Replace 'preserved' with 'true' or 'false' to preserve the spawn.

Example: Yanfly.SpawnEventAt(1, 5, 30, 40, true)
- Map 1's Event 5 will be spawned at X, Y coordinates: 30, 40.
- This event will be preserved.

Example: Yanfly.SpawnEventAt(2, 10, 50, 60, false)
- Map 2's Event 10 will be spawned at X, Y coordinates: 50, 60.
- This event will NOT be preserved.

- - -

Yanfly.SpawnEventTemplateAt(template, x, y, preserved)
- This will spawn the desired event by template name at the coordinates.
- Replace 'template' with a name from the 'Template Names' plugin param.
This must be in 'string' form (surround the name with quotes).
- Replace 'x' with the X position on the map to spawn the event at.
- Replace 'y' with the Y position on the map to spawn the event at.
- The X and Y positions MUST NOT have an event present at that location.
- Replace 'preserved' with 'true' or 'false' to preserve the spawn.

Example: Yanfly.SpawnEventTemplateAt('StrawberryPlant', 30, 40, true)
- The 'StrawberryPlant' template from the plugin parameters will be
spawned at X, Y coordinates: 30, 40.
- This event will be preserved.

Example: Yanfly.SpawnEventTemplateAt('MineralVein', 50, 60, false)
- The 'MineralVein' template from the plugin parameters will be
spawned at X, Y coordinates: 50, 60.
- This event will NOT be preserved.

- - -

Yanfly.SpawnEventInRegion(mapId, eventId, region, preserved)
- This will spawn the desired event at a random place within a region(s).
- Replace 'mapId' with the ID of the map with the event to morph into.
- Replace 'eventId' with the ID of the event to morph the target into.
- Replace 'region' with the ID of the region to spawn the event into.
If you want to use multiple regions, place them in an array.
- Replace 'preserved' with 'true' or 'false' to preserve the spawn.

Example: Yanfly.SpawnEventInRegion(1, 5, 20, true)
- Map 1's Event 5 will be spawned at a random point in region 20.
- This event will be preserved.

Example: Yanfly.SpawnEventInRegion(2, 10, [20, 25], true)
- Map 2's Event 10 will be spawned at a random point in regions 20 or 25.
- This event will NOT be preserved.

- - -

Yanfly.SpawnEventTemplateInRegion(template, region, preserved)
- This will spawn the desired event at a random place within a region(s).
- Replace 'template' with a name from the 'Template Names' plugin param.
This must be in 'string' form (surround the name with quotes).
- Replace 'region' with the ID of the region to spawn the event into.
If you want to use multiple regions, place them in an array.
- Replace 'preserved' with 'true' or 'false' to preserve the spawn.

Example: Yanfly.SpawnEventTemplateInRegion('StrawberryPlant', 20, true)
- The 'StrawberryPlant' template from the plugin parameters will be
spawned at a random point in region 20.
- This event will be preserved.

Example: Yanfly.SpawnEventTemplateInRegion('MineralVein', [20, 25], true)
- The 'MineralVein' template from the plugin parameters will be
spawned at a random point in regions 20 or 25.
- This event will NOT be preserved.

- - -

Note: If a spawned event is preserved, it will remain on that map when the
map is reloaded from a save file or revisited from a different map. If an
event is set up to not be preserved, it will automatically despawn itself
upon leaving the map.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Obtaining Spawned Event Data - Script Calls
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

$gameMap.event(eventId)
- This will grab the event as an object.
- Replace 'eventId' with the ID of the event you wish to grab.
- ID's past 1000 (or whatever you've set it to in the plugin parameters)
are spawned events.

- - -

$gameMap.FirstSpawnedEvent()
- This will grab the first available spawned event as an object.
- If the first event has been despawned, the next on in the list will be
returned as an object. If there are no spawned events left, this script
call will return an undefined value.

- - -

$gameMap.FirstSpawnedEventID()
- This will grab the first available spawned event's ID as a number.
- If the first event has been despawned, the next on in the list will be
returned as a number. If there are no spawned events left, this script
call will return a value of 0.

- - -

$gameMap.LastSpawnedEvent()
- This will grab the last available spawned event as an object.
- If the last event has been despawned, the previous event in the list
will be returned as an object. If there are no spawned events left, this
script call will return an undefined value.

- - -

$gameMap.LastSpawnedEventID()
- This will grab the last available spawned event's ID as a number.
- If the last event has been despawned, the previous event ID on in the
list will be returned as a number. If there are no spawned events left,
this script call will return a value of 0.

- - -

$gameSystem.getMapSpawnedEventTotal()
- Returns the total number of spawned events on that map ever (this number
will include the spawned events that have despawned).

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Despawn Event - Script Calls
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Yanfly.DespawnEventID(eventId)
- Despawn a target spawned event if you have the spawned event's ID.
- Replace 'eventId' with the spawned event's ID.

Example: Yanfly.DespawnEventID(1001)
- This will despawn event 1001 on the current map.
- The latest spawned event is no longer preserved.

Example: Yanfly.DespawnEventID($gameMap.LastSpawnedEventID())
- This will despawn the last spawned event based on ID on the current map.
- Event 1001 is no longer preserved.

- - -

Yanfly.DespawnEvent(event)
- Despawn a target spawned event object.
- Replace 'event' with the spawned event object.

Example: Yanfly.DespawnEvent($gameMap.FirstSpawnedEvent())
- This will despawn the first spawned event on the current map.
- First spawned event is no longer preserved.

- - -

Yanfly.ClearSpawnedEvents()
- Clears the current map of all spawned events.

- - -

Yanfly.ClearSpawnedEvents(mapId)
- Clears a specific map of all spawned events.
- Replace 'mapId' with the mpa you wish to clear of spawned events.

Example: Yanfly.ClearSpawnedEvents(10)
- Clears all spawned events on map 10.

Note: When a spawned event is despawned, any preserved data will also be
removed in addition to the removed spawned event.

============================================================================
Changelog
============================================================================

Version 1.01:
- Bugfixed for irregular spawn ID's.

Version 1.00:
- Finished Plugin!

============================================================================
End of Helpfile
============================================================================