What is the Map Overlay Feature?
[!NOTE] To read this file the intended way, open this file using Visual Studio Code (VSCode) and type CTRL+K, then V. It will open the preview of this file. You can also read it on the official GitLab repository of PSDK. Enjoy your reading!
A Map Overlay is a configurable shader that is visible in the overworld. Tired of plain tone blending? Now your game can show a complex underwater effect, sunrays coming from above, or a radar wave emanating from a tile you specify!
Despite relying on shaders, Map Overlays can be started, stopped, and manipulated in a user-friendly way, directly from event commands, with no more coding knowledge than the rest of PSDK. Multiple presets have already been implemented, so you can start testing the feature right away, and you've also been given the ability to freely change their settings.
You can also create your very own Map Overlay presets if you're feeling adventurous: see Create your own Map Overlay for details. The only limits of Map Overlays are your patience and imagination!
Prerequisites
For the feature to work as intended, make sure to add the default map overlay shader files to your graphics/shaders/ folder, as well as noise_texture.png and water_color_gradient.png in graphics/fogs/.
Basics
In the following tutorial, we will explain the basics of manipulating an existing Map Overlay.
Existing presets
At the time of writing, the available presets are:
:static_image:scroll:water:fog:nausea:ripple:godrays
Their corresponding shader files are named overlay_<preset>.frag and registered as :overlay_shader_<preset>. For example, the :water preset corresponds to overlay_water.frag, which is registered as :overlay_shader_water. If you are missing the shader file, you will see an error in the console when trying to start the shader.
For reference, all Interpreter commands of the Map Overlay are in 160 Interpreter_Overlay.rb.
Starting a Map Overlay Preset
To start a Map Overlay, run the Interpreter command start_overlay. For example: start_overlay(:water). This can be done from an event directly, or in the console: S.MI.start_overlay(:water).
start_overlay(:water)
Stopping the Map Overlay Feature
Run stop_overlay to restore the default simple tint shader on the map.
Pausing or Unpausing Shader Updates
You can pause or unpause the time update process of your Map Overlay with the preset attribute paused.
# Pause
map_overlay.paused = true
# Unpause
map_overlay.paused = false
The paused attribute default is set by the return value of preset method: animated?. If this method state the preset has no animation (false), then the paused attribute is true by default (and vice versa). You can monkey patch the animated? method.
Blend Modes
At the time of writing of this file, the available blend modes are the following:
:normal:add:subtract:multiply:overlay:screen
To set the blend mode, use map_overlay.blend_mode. The argument should be the blend mode of your choice.
Tilemap to UV Conversion and the position Attribute
Some shaders (such as ripple, static image, and scroll) use a position attribute to determine where on the map the effect is centered or targeted. This attribute is managed by the UvResolver class and the PresetWithPosition module and can be set in several flexible ways:
- With the Interpreter:
(:game_player)
# or
([15, 33])
# or
(PFM::MapOverlay::UVResolver.new([x, y]))
-
Game player coordinates:
.position = :game_player # or .position = PFM::MapOverlay::UVResolver.new(:game_player) -
Specific map coordinates (tile-based):
.position = [15, 33] # x=15, y=33 # or .position = PFM::MapOverlay::UVResolver.new([15, 33]) -
Directly with a UVResolver instance:
resolver = PFM::MapOverlay::UVResolver.new([x, y]) .position = resolver
If you assign a symbol or a two-number array, the system will automatically convert it to a UVResolver as needed.
Note: UVResolver currently only supports tile coordinates. Future updates may add support for other coordinate types.
The Map Affix Module
Both the :static_image and :scroll overlay presets share a common module called PresetWithMapAffix. This module provides a flexible way to "affix" (attach) the overlay to the map instead of the camera that follows the player. This is turned off by default, but can be enabled with the map_affix property.
Usage Example:
.map_affix = true
If you are developing a custom overlay preset, you can include the module as follows:
module PFM
class MapOverlay
class MyCustomOverlayPreset < PresetBase
prepend PresetWithMapAffix
#or
include PresetWithMapAffix
# ... your custom logic ...
end
end
end
// Function to compute the correct UV coordinates for the overlay to remain affixed to the map
vec2 resolve_overlay_uv(vec2 pixPos){
vec2 adjust = resolution / image_resolution / zoom;
vec2 displacement = (pixPos - vec2(position.x, -position.y));
return displacement * adjust;
}
vec4 your_preset(vec2 pixPos){
// your custom logic...
if(!map_affix) texture = vec4(texture2D(extra_texture, uv));
else texture = texture2D(extra_texture, resolve_overlay_uv(uv));
return texture;
}
// Entry point function
void main() {
//(...)
vec4 overlay = your_preset(vec2(gl_TexCoord[0].x,1.0 - gl_TexCoord[0].y));
//(...)
}
Create Your Own Map Overlay
Perhaps you have a very specific idea that's not covered by existing presets. Of course, you can create your very own Map Overlay! You could even share it with the community as a PSDK Plugin later.
In the following tutorial, we will learn how to create your own custom Map Overlay. We will use :preset as a placeholder for the symbol of your new Map Overlay; swap it out for your own custom symbol in your monkey-patch.
Please see /scripts/HOW_TO_CREATE_A_CUSTOM_SCRIPT.md for details on monkey-patching PSDK. Never change the base code of PSDK yourself unless you're contributing!
Registering Your Preset and Shader File
- Create a new .rb file in your
/scripts/folder containing the following:
# /scripts/00001 MyMapOverlay.rb
module PFM
class MapOverlay
# Custom image overlay
class PresetCustom < PresetBase
# <= Put the custom preset attributes here
private
# Name of the shader to load
# @return [Symbol]
def shader_name
:overlay_shader_preset # <= Name of the shader we will register in step 2
end
def initialize
super
# <= Put the custom preset attributes initialization here
end
# Update the preset in UI space
# @param preset [PresetCustom]
def update(preset)
super(preset)
# <= Call the preset attribute update functions here (eg. update_extra_texture(preset))
end
# <= Define the custom preset update functions here
def dispose
super
# <= Add the disposable resource dispose call here
end
end
register_preset(:preset, PresetCustom)
end
end
- Create and register your shader file (just create a blank .frag file for now):
Shader.register(:overlay_shader_preset, 'graphics/shaders/overlay_preset.frag', 'graphics/shaders/map_viewport.vert')
# Should go outside of the module
See Creating your own fragment shader for details.
Optional Step
If your Map Overlay requires regular updates (changes over time), add the following code to your preset class:
# Tell if the preset has an animation
# @return [Boolean]
def animated?
return true
end
Setting your Preset's attributes
You've registered your Map Overlay's symbol and shader, but PSDK doesn't know what parameters they need. To remedy that, you have to define the preset's initial attributes in its initialize method.
Once the attributes are defined, you need to define the UI update methods to handle changes in the attributes. This way the shader will know the most current preset attribute value on next update.
Example with the Godrays Effect:
# GodRays overlay
class PresetGodRaysOverlay < PresetBase
prepend PresetWithSampleColor
private
# Name of the shader to load
# @return [Symbol]
def shader_name
:overlay_shader_godrays
end
# Tell if the preset has an animation
# @return [Boolean]
def animated?
return true
end
# Initialize the Godrays preset
def initialize
super
@sample_color = Color.new(153, 102, 26, 128)
@blend_mode = :screen
end
end
register_preset(:godrays, PresetGodRaysOverlay)
end
You may be able to manually change the attributes value using map_overlay. (See Pausing or Unpausing Shader Updates)
Final Look
# Don't forget to swap "preset" with your own symbol!
Shader.register(:overlay_shader_preset, 'graphics/shaders/overlay_preset.frag', 'graphics/shaders/map_viewport.vert')
module PFM
class MapOverlay
# Static image overlay
class PresetCustom < PresetBase
# Get or set effect value
# @return [Integer]
attr_accessor :effect
private
# Name of the shader to load
# @return [Symbol]
def shader_name
:overlay_shader_preset
end
def initialize
super
@effect = 0
end
# Update the preset in UI space
# @param preset [PresetCustom]
def update(preset)
super(preset)
update_effect(preset)
end
# Update the preset effect in UI space
# @param preset [PresetCustom]
def update_effect(preset)
return if @effect == preset.effect
@shader.set_int_uniform('effect', @effect = preset.effect)
end
end
register_preset(:preset, PresetCustom)
end
end
That's it for the Ruby side. Next up: the fragment shader!
Creating Your Own Fragment Shader
The shaders provided with this feature contain plenty of examples and helper functions, removing the need for you to come up with everything on your own. You are free to copy anything in them to make your own fragment shader.
Nevertheless, it is better to have a basic understanding of shaders before touching them. Here are some resources:
A 5 minutes tutorial video that explains shaders in simple terms by PlayWithFurcifer on YouTube
The Book of Shaders, a step-by-step tutorial (in depth)
Requirements
-
A Map Overlay shader needs to be compatible with PSDK's color_process and tone_process
-
Keeping compatibility with the Map Overlay's blend modes is strongly recommended
-
Your new shader should preferably be named after your preset:
overlay_preset.frag
If not starting from an existing preset's shader, you can use the Minimum compatibility Map Overlay shader file below.
Minimum compatibility Map Overlay shader
As helper functions have been removed from the minimum file, please refer to existing presets' files for them.
Minimum Map Overlay GLSL File
//uniform keeping track of the blend mode
// 0: normal (mix)
// 1: add
// 2: subtract
// 3: multiply
// 4: overlay
// 5: screen
uniform int blend_mode = 0;
//// compatibility with other SpritesetMap shaders
const vec3 lumaF = vec3(.299, .587, .114);
uniform vec4 color = vec4(0.0, 0.0, 0.0, 0.0);
uniform vec4 tone = vec4(0.0, 0.0, 0.0, 0.0);
////
//uniform keeping track of base texture
uniform sampler2D texture;
//uniform keeping track of the time variable
uniform float time;
//uniform keeping track of the opacity variable
uniform float opacity = 1.0;
//constant keeping track of a small number for comparison purposes
const float SMALL_NUMBER = 0.0001;
//function to compute the overlay blend mode effect
vec4 overlay_blend_mode(vec4 base, vec4 blend1)
{
vec4 limit = step(0.5, base);
return mix(2.0 * base * blend1, 1.0 - 2.0 * (1.0 - base) * (1.0 - blend1), limit);
}
// function to compute the screen blend mode effect
vec4 screen(vec4 base, vec4 blend)
{
return 1.0 - (1.0 - base) * (1.0 - blend);
}
// account for opacity in blend modes
vec3 blend(vec3 frag, vec3 overlay, float overlay_opacity)
{
float base_opacity = 1.0 - overlay_opacity;
return step(SMALL_NUMBER, float(blend_mode==0)) * mix(frag, overlay, overlay_opacity)
+ step(SMALL_NUMBER, float(blend_mode==1)) * (frag * base_opacity + (overlay + frag) * overlay_opacity)
+ step(SMALL_NUMBER, float(blend_mode==2)) * (frag * base_opacity + (overlay - frag) * overlay_opacity)
+ step(SMALL_NUMBER, float(blend_mode==3)) * (frag * base_opacity + (overlay * frag) * overlay_opacity)
+ step(SMALL_NUMBER, float(blend_mode==4)) * overlay_blend_mode(vec4(frag, 1.0),vec4(overlay.rgb, overlay_opacity)).rgb
+ step(SMALL_NUMBER, float(blend_mode==5)) * screen(vec4(frag, 1.0),vec4(overlay.rgb, overlay_opacity)).rgb;
}
// account for blend mode
// 0: normal (mix)
// 1: add
// 2: subtract
// 3: multiply
// 4: overlay
vec4 account_for_blend_mode(vec4 frag, vec4 overlay)
{
float overlay_opacity = opacity * overlay.a;
return vec4(blend(frag.rgb,overlay.rgb,overlay_opacity),frag.a);
}
// Your preset's code goes here
vec4 preset(vec2 pixPos)
{
return texture2D(texture, pixPos);
}
//main function where everything happens
void main() {
//load the base texture
vec4 frag = texture2D(texture, gl_TexCoord[0].xy);
//overlay presets
vec4 overlay = preset(gl_TexCoord[1].xy);
//set the final color
frag = account_for_blend_mode(frag,overlay);
////compability with color_process
frag.rgb = mix(frag.rgb, color.rgb, color.a);
////compability with tone_process
float luma = dot(frag.rgb, lumaF);
frag.rgb = mix(frag.rgb, vec3(luma), tone.a);
frag.rgb += tone.rgb;
////
gl_FragColor = frag;
}