Map Changing Tutorial by NeoLogiX - Revision history

Apollolux: /* Notes */ cleanup, add set person coordinate note

2014-03-10T23:00:08Z

‎Notes: cleanup, add set person coordinate note

Apollolux: /* Advanced Method */

2014-03-10T22:22:35Z

‎Advanced Method

Apollolux: /* Simple Method */ "end here" note

2014-03-08T18:38:21Z

‎Simple Method: "end here" note

Apollolux: /* Transition Manager */ fade.init default assign trick

2014-03-08T17:51:14Z

‎Transition Manager: fade.init default assign trick

Apollolux: created

2014-03-08T06:13:04Z

created

New page

The most common activity in an RPG is walking on a map. A map usually contains places to visit so the game needs to be able to "warp" the player from one map (usually an overworld map) to another (usually a town or dungeon), or vice versa. This tutorial offers two practical, usable methods to scripting a change of map.

__TOC__

==Simple Method==
<syntaxhighlight>
var mapfile = "overworld.rmp";
ChangeMap(mapfile);
</syntaxhighlight>

Sphere has a built-in function [[API:ChangeMap|ChangeMap]] that handles all the behind-the-scenes work of switching from one map to another. It requires the [[API:MapEngine|map engine]] to be [[API:IsMapEngineRunning|running]], otherwise Sphere will abort with an error telling you that the map engine isn't running. If you don't care about any special visual effects taking place during a map change, all you need to do is call ''ChangeMap'' with the file name of the new map.

===Triggering===
The most common way to activate a change-of-map within a Sphere map is to put a Trigger entity on the same layer as the [[API:GetInputPerson|expected input person]] and add the map change code to it. In actuality, as long as the map engine is running ''ChangeMap'' can be called at any time.

==Advanced Method==
This tutorial exists because Sphere users often want to see visual effects during a map change. The following is sample code for a transition manager, sectioned by purpose.

===Easing===
[http://www.robertpenner.com/easing/ Robert Penner] presented "a collection of swappable functions that [http://www.gizma.com/easing/ add flavor] [http://easings.net/ to motion]." He called them "easing functions" because they "ease" an animation. This is the essence of ''tweening'' and can be a very powerful tool for animation.

For the sake of simplicity in this tutorial, easing functions take a value from 0.0 to 1.0, representing the percentage of animation completed, and will return a value based on that value's place on a given curve.

====Linear Ease====
A ''linear ease'' is the easing function version of normal linear interpolation. Given a time value from 0.0 to 1.0, it will simply return that value.

<syntaxhighlight>
function linear(t){return t*1.0;}
</syntaxhighlight>

Other easing functions can be written to create more natural-looking animations or to use with some less common screen transitions. Visit the links at the bottom for more info.

===Effect===
A screen transition requires an effect to use. For this tutorial, we will take one second (1000 milliseconds) to fade between two maps; the old map fades into the new one.

For the sake of simplicity in this tutorial, effects functions will only take the before-image, the after-image, the percentage of time completed, and an easing function to transform the time percentage into a percentage to multiply the old image's alpha value.

<syntaxhighlight>
function fade(a, b, t, ease) {
var alpha = (ease(1.0-t)*255);
b.blit(0,0);
a.blitMask(0,0, CreateColor(255,255,255, alpha|0));
}
</syntaxhighlight>

The above function simply fades the old image on top of the new image; setting <var>t</var> to 1.0 (i.e. the end of the animation) will render the old image completely transparent, showing the new image unobstructed.

===Transition Manager===
For convenience, this tutorial demonstrates a simple a transition manager that will initialize a transition, perform the transition over a given amount of time, then prepare the new image for use once the transition completes. <code>Transition</code> takes the before-image, the after-image, the effect function to use, the easing function to use to smooth the animation, the amount of time (in milliseconds) to perform the transition, and an extra object to hold data specific to the given instance of the transition.

<syntaxhighlight>
function Transition(before, after, effect, easing, ms, data) {
if ('init' in effect) effect.init(data);
var start = GetTime(), end = start+ms, time;
while ((time=GetTime())<end) {
effect(before, after, (time-start)/ms, easing);
FlipScreen();
}
after.blit(0,0);
}
</syntaxhighlight>

As you'll see at the beginning of the function, <code>Transition</code> will initialize the given effect with the extra data; the <code>fade</code> effect function above, for example, can be modified to take a color for tinting the old image:

<syntaxhighlight>
/**** add the following AFTER defining the fade function ****/
fade.prototype.init = function(data) {
this.color = 'color' in data?data['color']:CreateColor(255,255,255,255);
};
</syntaxhighlight>

...but for it to take effect, the above fade function has to be modified to actually use it:

<syntaxhighlight>
/**** modified fade function; keep this before defining its init() method ****/
function fade(a, b, t, ease) {
var h = 'color' in this?1:0;
var c = CreateColor(
h?this.color.red:255,
h?this.color.green:255,
h?this.color.blue:255,
h?this.color.alpha:255
);
c.alpha = (ease(1.0-t)*c.alpha)|0;
b.blit(0,0);
a.blitMask(0,0, c);
}
</syntaxhighlight>

===Triggering===
For this tutorial, a map change with screen transition follows the same conditions as a regular map change: it can be activated at any time as long as the map engine is running and the most common method to activate it is to put the required code in a Trigger entity on the map. Below is sample code that can be used for changing maps with the fade effect (the modified one that allows adding a custom tint) and linear easing we defined earlier:

<syntaxhighlight>
var SW = GetScreenWidth(), SH = GetScreenHeight();
var before = GrabImage(0,0, SW,SH), ms = 1000;
ChangeMap("newmap.rmp");
RenderMap();
var after = GrabImage(0,0, SW,SH);
Transition(before, after, fade, linear, ms, {'color':CreateColor(255,255,255,255)});
</syntaxhighlight>

==Notes==
Keep in mind the transition manager and the associated code defined in this tutorial is extremely simplistic. The concept of initializing a given effect is an example of possible additions to its functionality and for more advanced effects like "mosaic" or "piecemeal blackout" this initialization step is essential. The sample fade transition also uses only two images and fixes the coordinates for them at (0,0); a possible edit that can be made would allow use of different coordinates and/or more than just two images.

Another possible modification that can be made is separating the transition's rendering and updating and attaching them to [[API:SetRenderScript|a render script]] and [[API:SetUpdateScript|an update script]], respectively, instead of running the whole transition as a blocking function. This is an advanced exercise that should be performed once you feel more comfortable with render and update scripting.

==See also==
* [http://www.robertpenner.com/easing/ Robert Penner's easing functions]
* [http://www.gizma.com/easing/ A visual easing function editor]
* [http://easings.net/ Easing functions cheat sheet]
* [http://upshots.org/actionscript/jsas-understanding-easing Understanding easing]

==In closing==
If there are any questions, you can ask at the forums or the Talk. Enjoy transitioning your maps! --[[User:Apollolux|Apollolux]] ([[User talk:Apollolux|talk]]) 06:13, 8 March 2014 (UTC)

[[Category:Tutorials]]

@@ Line 121: / Line 121: @@
 ==Notes==
-Keep in mind the transition manager and the associated code defined in this tutorial is extremely simplistic. The concept of initializing a given effect is an example of possible additions to its functionality and for more advanced effects like "mosaic" or "piecemeal blackout" this initialization step is essential. The sample fade transition also uses only two images and fixes the coordinates for them at (0,0); a possible edit that can be made would allow use of different coordinates and/or more than just two images.
+Keep in mind the transition manager and the associated code defined in this tutorial is (mostly) extremely simplistic. The concept of initializing a given effect is an example of possible additions to its functionality and for more advanced effects like "mosaic" or "piecemeal blackout" this initialization step is essential. The sample fade transition also uses only two images and fixes the screen coordinates for them at (0,0); a possible edit that can be made would allow use of different coordinates and/or more than just two images.
 Another possible modification that can be made is separating the transition's rendering and updating and attaching them to [[API:SetRenderScript|a render script]] and [[API:SetUpdateScript|an update script]], respectively, instead of running the whole transition as a blocking function. This is an advanced exercise that should be performed once you feel more comfortable with render and update scripting.

@@ Line 18: / Line 18: @@
 ==Advanced Method==
-This tutorial exists because Sphere users often want to see visual effects during a map change. The following is sample code for a transition manager, sectioned by purpose.
+This tutorial exists because Sphere users often want to see visual effects during a map change. Commonly known as a "transition" or "screen transition," this visual effect adds some "juice" to your game by making a gradual map change look more fantastical or even "realistic" than a sudden swap; random blocks or pixels fading in or out looks more like a fantasy teleportation, a fade in our out looks more like going into a dark place from a light place or coming out of that dark place to a much lighter one, and so on.
-===Easing===
+A convenient way to manage the transitions needed for a map change (or for that matter any screen transition in general) is by using a general purpose transition manager that allows for configuration. Certain functionalities can be split out to be independent of the transition manager so that they can be used at any time. We shall now create a transition manager piece by piece.
-For the sake of simplicity in this tutorial, easing functions take a value from 0.0 to 1.0, representing the percentage of animation completed, and will return a value based on that value's place on a given curve.
+===Animation Speed===
 ====Linear Ease====
-A ''linear ease'' is the easing function version of normal linear interpolation. Given a time value from 0.0 to 1.0, it will simply return that value.
+A ''linear ease'' is the easing function version of normal linear interpolation.
 <syntaxhighlight>
-function linear(t){return t*1.0;}
+function linear(t, b, c, d) { return c*t/d + b; }
 </syntaxhighlight>
 Other easing functions can be written to create more natural-looking animations or to use with some less common screen transitions. Visit the links at the bottom for more info.
-===Effect===
+===Animation Effect===
 A screen transition requires an effect to use. For this tutorial, we will take one second (1000 milliseconds) to fade between two maps; the old map fades into the new one.
-For the sake of simplicity in this tutorial, effects functions will only take the before-image, the after-image, the percentage of time completed, and an easing function to transform the time percentage into a percentage to multiply the old image's alpha value.
+Effects functions in this transition manager will take the before-image, the after-image, the start time, the length of time for the animation, the current time, and an easing function to transform the time into an alpha value for the old image.
 <syntaxhighlight>
-function fade(a, b, t, ease) {
+function fade(a, b, ts, ms, tn, ease) {
-	var alpha = (ease(1.0-t)*255);
+	var alpha = ease(tn-ts, 255, -255, ms);
 	b.blit(0,0);
 	a.blitMask(0,0, CreateColor(255,255,255, alpha|0));
@@ Line 47: / Line 54: @@
 </syntaxhighlight>
-The above function simply fades the old image on top of the new image; setting <var>t</var> to 1.0 (i.e. the end of the animation) will render the old image completely transparent, showing the new image unobstructed.
+===The Transition Manager===
+We will now create the actual transition manager that will initialize a transition, perform the transition over a given amount of time, then prepare the new image for use once the transition completes. <code>Transition</code> takes the before-image, the after-image, the effect function to use, the easing function to use to smooth the animation, the amount of time (in milliseconds) to perform the transition, and an extra object to hold data specific to the given instance of the transition.
 <syntaxhighlight>
@@ Line 58: / Line 64: @@
 	var start = GetTime(), end = start+ms, time;
 	while ((time=GetTime())<end) {
-		effect(before, after, (time-start)/ms, easing);
+		effect(before, after, start, ms, time, easing);
 		FlipScreen();
+	}
@@ Line 78: / Line 84: @@
 <syntaxhighlight>
 /**** modified fade function; keep this before defining its init() method ****/
-function fade(a, b, t, ease) {
+function fade(a, b, ts, ms, tn, ease) {
 	var h = 'color' in this?1:0;
 	var c = CreateColor(
@@ Line 86: / Line 92: @@
 		h?this.color.alpha:255
 	);
-	c.alpha = (ease(1.0-t)*c.alpha)|0;
+	c.alpha = ease(tn-ts, c.alpha, -c.alpha, ms)|0;
 	b.blit(0,0);
 	a.blitMask(0,0, c);
+}
 </syntaxhighlight>
 ===Triggering===
@@ Line 103: / Line 111: @@
 Transition(before, after, fade, linear, ms, {'color':CreateColor(255,255,255,255)});
 </syntaxhighlight>
 ==Notes==

@@ Line 67: / Line 67: @@
 /**** add the following AFTER defining the fade function ****/
 fade.prototype.init = function(data) {
-	this.color = 'color' in data?data['color']:CreateColor(255,255,255,255);
+	this.color = (data && data.color) || CreateColor(255,255,255,255);
 };
 </syntaxhighlight>