Sometimes you need to update the hotspot material (the hotspot texture), like when your mouse pointer is over the hotspot, or when you just need to change from a state to another like on a checkbox.
Hotspots states are here to do this job. You can declare several states on your hotspots and change their state dynamically.

States definition

In the hotspot property, we find a states object, which contains the different states of your hotspot. For now, state handles only the material change of the hotspot.
By default if you declare a state named over, it will be used as the state when your mouse is over the hotspot. In the following example we change the image url of the material:

"hotspots":
[
    {
        "uid": "hotspot-0",
        "material":
        {
            "image": "hotspot-out.jpg"
        },
        "states":
        {
            "over": 
            {
                "material":
                {
                    "image": "hotspot-over.jpg"
                }
            }
        }
    }
]

The over state will override the material configuration of your hotspot.

Using a sprite map

Sprite maps are images with all states in a single image. Each state will declare a frame object which defines the final material texture location in the sprite map. Here is what the sprite map we use in this tutorial looks like, it's a 512x512 image and each state is 256x256.

"hotspots":
[
    {
        "uid": "hotspot-0",
        "material":
        {
            "image": 
            {
                "url": "hotspot-map.jpg",
                "frame": { "x": 0, "y": 0, "w": 256, "h": 256 }
            }
        },
        "states":
        {
            "over": 
            {
                "material":
                {
                    "image":
                    {
                        "frame": { "x": 256, "y": 0, "w": 256, "h": 256 }
                    }
                }
            }
        }
    }
]

The global material declaration (at the root of the hotspot) has an image configuration with two properties:

  • image.url - The url of the sprite map.
  • image.frame - The frame coordinates in the sprite map.

In the over state, we just override the frame, the image url will remain the same! The frame.x is now at 256 and the final texture will be the blue circle with the number one.

Prevent the over state

By default if there is an over state available, ForgeJS will load the over state when your mouse is over the hotspot and restore the default material when you are out. If you want to prevent this behavior you can set the auto property to false.

"hotspots":
[
    {
        "uid": "hotspot-0",
        "material": { ... },
        "states":
        {
            "auto": false
        }
    }
]

Toggle custom states

You can declare as many states as you want and change the state of the hotspot dynamically with javascript or with an action declared in the json. In the following example we will have four states matching the four circles in our sprite map. Then we will declare an action to toggle through these four states when the user clicks on the hotspot.

"hotspots":
[
    {
        "uid": "hotspot-states-toggle",
        "facingCenter": true,

        "transform": { ... },

        "geometry": { ... },

        "material":
        {
            "image":
            {
                "url": "hotspot-map.png"
            },

            "transparent": true
        },

        "states":
        {
            "default": "two",
            "auto": false,

            "zero":
            {
                "material":
                {
                    "image":
                    {
                        "frame": { "x": 0, "y": 0, "w": 256, "h": 256 }
                    }
                }
            },

            "one":
            {
                "material":
                {
                    "image":
                    {
                        "frame": { "x": 256, "y": 0, "w": 256, "h": 256 }
                    }
                }
            },

            "two":
            {
                "material":
                {
                    "image":
                    {
                        "frame": { "x": 0, "y": 256, "w": 256, "h": 256 }
                    }
                }
            },

            "three":
            {
                "material":
                {
                    "image":
                    {
                        "frame": { "x": 256, "y": 256, "w": 256, "h": 256 }
                    }
                }
            }
        },

        "events":
        {
            "onClick": "toggle-state"
        }
    }
]

Here we have the four states, named one, two, three and four. We set the default property of the states object to two. This way the defaut texture frame will be on the number 2! Then we declare an action on the onClick event called toggle-state. This action will ask the hotspot to loop through its states. Here what the action declaration looks like:

{
    "story": { ... },

    "actions":
    [
        {
            "uid": "toggle-state",
            "target":
            {
                "identifier": "hotspot-states-toggle",
                "accessor": "states"
            },
            "method":
            {
                "name": "toggle"
            }
        }
    ]
}

This action targets the states property of the hotspot-states-toggle hotspot, and executes its toggle method that will load the next available state.

24th Apr 2017