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:
update_overlay_position(:game_player)
# or
update_overlay_position([15, 33])
# or
update_overlay_position(PFM::MapOverlay::UVResolver.new([x, y]))
  • Game player coordinates:

    map_overlay.position = :game_player
    # or
    map_overlay.position = PFM::MapOverlay::UVResolver.new(:game_player)
    
  • Specific map coordinates (tile-based):

    map_overlay.position = [15, 33] # x=15, y=33
    # or
    map_overlay.position = PFM::MapOverlay::UVResolver.new([15, 33])
    
  • Directly with a UVResolver instance:

    resolver = PFM::MapOverlay::UVResolver.new([x, y])
    map_overlay.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_overlay.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

  1. 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
  1. 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;

}