Actor Tutorial – Advanced Topics – Region Actors, Actor Queries, and Query Response Actors
The purpose of this tutorial is to explain the Region Actors, the Query actor messages and the Query Response Actor, and how they are linked together to produce certain effects.
Overview
Normally one uses Effect and Behavior Actor Events to dynamically alter the appearance of units or do other actor related things (Change unit colors, size, start animations, etc.). However, Doodads and other non Unit Actors can not be subject to effects or behaviors, so how does one go about sending actor messages to them? A simple example of this is in action is the Nuke. How does it make the trees light on fire, if they are not units? With Region Actors, Query Messages and Query Response Actors, one can do this. In this tutorial, I will show a Unit wandering through the forest, and have the trees grow larger as the unit approaches them, and shrink back down when it leaves. Also the closet tree will be changed to pink.
Regions
Region actors come in 7 kinds: Rectangle, Circle, Game Arc, Water, Polygon and Combine (This last one combines other region actors to form a new one). The first 2 are the most common to be used. Region Actors are Actors that encompass a region. Note that they are NOT visible, they are just used to define an area for a Query later. For this tutorial we will use a Circle Region actor. We will create a Circle Region Actor and call it Shiny Trees.
Like any other actor, they can inherit their position from a Host, so a Region actor can be created that is static, but also can be mobile. A simple example of a moving Circle Region actor is the AoE targeting, which has a Site Op to follow Scope Bearings (which in Ability Targeting is the cursor).
In the Circle Region Actor, you can define how large the circle region will be by setting the Radius Field. The Region actor can also use Unit Filters to limit the queries against the Region Actor. In our example, the Radius is set to 5. We will also set the Events to create this Actor when a Marine is created (there will only be one on the example map).
Queries
This is where things get interesting. A region actor can be queried for the actors within it. There are 2 types of Queries: Query Region and Query Persistent. Query Region is used to query a region actor directly. For this message you must specify the Region Actor you are querying, and the Query Response actor that will be used for all actors found in the region.
There are a few ways to alter how the query finds actor within a region, which is controlled by the Intersect Type drop down menu. If you hover over this menu, it will describe each item and how it affects the query. For this tutorial we will just use center, which means if the center of the actor is in the region, the actor is considered to be in the region.
Query Region only runs a query against the region once, for that event. Sometimes you may want to have the region being queried at a fixed rate as long a the region exists (As seen in AoE targeting). For this you have the Query Persistent message. This will be the Query we use for this tutorial. We can define how often the region is queried with the Refresh Period field, which we will leave at 0 (query at all times).
The other 5 fields define what the query does with the actors it finds. For the fields with “Response” in their name, they will need a Query Response Actor to be entered, which we will create later. For the Enter, this is the response that is used when an actor enters the region. For Leave, it is the same, but for when an Actor leaves the Region. For this tutorial, when an actor enters the region it will be scaled up to 2x its size over 3 seconds, and when it leaves, it will be scaled down to normal size over the same time period.
The Closest to Ref Key is the actor that is used as the center, in order to determine which actor is closest and thus which actor is used for the Becomes Closest Response and the No Longer Closest Response. In our tutorial, the Host actor, which is the Marine, will be the Key, and for the Becomes Closest Response, we will set the color of the tree to be Pink, and when it is no longer the closest, it will be set back to its normal color.
Query Response
Ok, for the final piece of the puzzle, Query Response. In the previous steps we created our Circle Region actor, and told it to Query itself. Now it has found actors, what to do with them? Query Response time.
First we will create our Query Response for when an actor enters the Region, and call it Grow.
The main 2 fields we are interested in is On Response and Subject. The first field controls what we do when we run the Query Response, which can be any actor related thing. Open up On Response.
For On Response, we can choose which scope the response is sent to, either the Query Subject (the scope of the Actor that was found by the query) or Query Director (the scope of the Actor that did the Query, in this case, our Marine). We want this message to be sent to the scope of the queried actors, so we will leave our scope as Query Subject.
For the Send, we want to send a Set Scale message, with 2x the scale over 3 seconds. We will set the Label to Grow (for later when we want to clear this).
For Target, we want the actor that was queried to be the Target, so we use the System Reference of Query Subject.
The Subject field is used to control and filter what this Query Response is sent to. For example, I may want this tree growing to only happen to Trees that have been on the map for a certain period of time. I would use the Age term to filter out trees that have not been present on the map for the necessary time. Filters will accept a comma delimited list of Actor Types, so for example, I may want only Trees to be affected by this action, so I could set all trees to have an Actor Alias of _Trees, and put _Trees in this field. For all of our responses, we will want to set the Filters to Doodad, so it knows to send the response to Doodad actors.
The Subject field is an array like the On Response field, with filters/terms of a Subject entry corresponding to the respective On Response entry. This would allow us to make a Query Response that does different things depending on Filters. Following the earlier example, perhaps I would want trees of a certain age to be scaled to 2 times, whereas younger trees be scaled to 1.5 times.
Now we will create the remaining responses. For our Leave Response, we want to clear the earlier Set Scale, so we now create a Query Response Actor called Shrink, and have it send a Clear Scale message to the Query Subject, using the Label we set earlier.
We now create our Becomes Closest and No Longer Closest Responses. In the first case, we want to set the actor color to pink, and in the second we want the color to be cleared. We will call these actors On Pink and Off Pink respectively
Here is what your On Pink On Response should look like
And this is what your Off Pink On Response should look like
Now to wrap it all up, we go back to our Query Persistent message in our Circle Region Actor (Shiny Trees), and set the fields to the correct responses.
Congrats, now run the map and watch as trees grow around the marine, and the closest tree turns pink!
Not a bad tutorial. The query persistent must be a new one since I played with them. You can have fun combining them with reference set event actions. Check my turret simulation demo map to see what I did with them (note was before HOTS).
Rollback Post to RevisionRollBack
Contribute to the wiki (Wiki button at top of page) Considered easy altering of the unit textures?
Actor Tutorial – Advanced Topics – Region Actors, Actor Queries, and Query Response Actors
The purpose of this tutorial is to explain the Region Actors, the Query actor messages and the Query Response Actor, and how they are linked together to produce certain effects.
Overview
Normally one uses Effect and Behavior Actor Events to dynamically alter the appearance of units or do other actor related things (Change unit colors, size, start animations, etc.). However, Doodads and other non Unit Actors can not be subject to effects or behaviors, so how does one go about sending actor messages to them? A simple example of this is in action is the Nuke. How does it make the trees light on fire, if they are not units? With Region Actors, Query Messages and Query Response Actors, one can do this. In this tutorial, I will show a Unit wandering through the forest, and have the trees grow larger as the unit approaches them, and shrink back down when it leaves. Also the closet tree will be changed to pink.
Regions
Region actors come in 7 kinds: Rectangle, Circle, Game Arc, Water, Polygon and Combine (This last one combines other region actors to form a new one). The first 2 are the most common to be used. Region Actors are Actors that encompass a region. Note that they are NOT visible, they are just used to define an area for a Query later. For this tutorial we will use a Circle Region actor. We will create a Circle Region Actor and call it Shiny Trees.
Like any other actor, they can inherit their position from a Host, so a Region actor can be created that is static, but also can be mobile. A simple example of a moving Circle Region actor is the AoE targeting, which has a Site Op to follow Scope Bearings (which in Ability Targeting is the cursor).
In the Circle Region Actor, you can define how large the circle region will be by setting the Radius Field. The Region actor can also use Unit Filters to limit the queries against the Region Actor. In our example, the Radius is set to 5. We will also set the Events to create this Actor when a Marine is created (there will only be one on the example map).
Queries
This is where things get interesting. A region actor can be queried for the actors within it. There are 2 types of Queries: Query Region and Query Persistent. Query Region is used to query a region actor directly. For this message you must specify the Region Actor you are querying, and the Query Response actor that will be used for all actors found in the region.
There are a few ways to alter how the query finds actor within a region, which is controlled by the Intersect Type drop down menu. If you hover over this menu, it will describe each item and how it affects the query. For this tutorial we will just use center, which means if the center of the actor is in the region, the actor is considered to be in the region.
Query Region only runs a query against the region once, for that event. Sometimes you may want to have the region being queried at a fixed rate as long a the region exists (As seen in AoE targeting). For this you have the Query Persistent message. This will be the Query we use for this tutorial. We can define how often the region is queried with the Refresh Period field, which we will leave at 0 (query at all times).
The other 5 fields define what the query does with the actors it finds. For the fields with “Response” in their name, they will need a Query Response Actor to be entered, which we will create later. For the Enter, this is the response that is used when an actor enters the region. For Leave, it is the same, but for when an Actor leaves the Region. For this tutorial, when an actor enters the region it will be scaled up to 2x its size over 3 seconds, and when it leaves, it will be scaled down to normal size over the same time period.
The Closest to Ref Key is the actor that is used as the center, in order to determine which actor is closest and thus which actor is used for the Becomes Closest Response and the No Longer Closest Response. In our tutorial, the Host actor, which is the Marine, will be the Key, and for the Becomes Closest Response, we will set the color of the tree to be Pink, and when it is no longer the closest, it will be set back to its normal color.
Query Response
Ok, for the final piece of the puzzle, Query Response. In the previous steps we created our Circle Region actor, and told it to Query itself. Now it has found actors, what to do with them? Query Response time.
First we will create our Query Response for when an actor enters the Region, and call it Grow.
The main 2 fields we are interested in is On Response and Subject. The first field controls what we do when we run the Query Response, which can be any actor related thing. Open up On Response.
For On Response, we can choose which scope the response is sent to, either the Query Subject (the scope of the Actor that was found by the query) or Query Director (the scope of the Actor that did the Query, in this case, our Marine). We want this message to be sent to the scope of the queried actors, so we will leave our scope as Query Subject.
For the Send, we want to send a Set Scale message, with 2x the scale over 3 seconds. We will set the Label to Grow (for later when we want to clear this).
For Target, we want the actor that was queried to be the Target, so we use the System Reference of Query Subject.
The Subject field is used to control and filter what this Query Response is sent to. For example, I may want this tree growing to only happen to Trees that have been on the map for a certain period of time. I would use the Age term to filter out trees that have not been present on the map for the necessary time. Filters will accept a comma delimited list of Actor Types, so for example, I may want only Trees to be affected by this action, so I could set all trees to have an Actor Alias of _Trees, and put _Trees in this field. For all of our responses, we will want to set the Filters to Doodad, so it knows to send the response to Doodad actors.
The Subject field is an array like the On Response field, with filters/terms of a Subject entry corresponding to the respective On Response entry. This would allow us to make a Query Response that does different things depending on Filters. Following the earlier example, perhaps I would want trees of a certain age to be scaled to 2 times, whereas younger trees be scaled to 1.5 times.
Now we will create the remaining responses. For our Leave Response, we want to clear the earlier Set Scale, so we now create a Query Response Actor called Shrink, and have it send a Clear Scale message to the Query Subject, using the Label we set earlier.
We now create our Becomes Closest and No Longer Closest Responses. In the first case, we want to set the actor color to pink, and in the second we want the color to be cleared. We will call these actors On Pink and Off Pink respectively
Here is what your On Pink On Response should look like
And this is what your Off Pink On Response should look like
Now to wrap it all up, we go back to our Query Persistent message in our Circle Region Actor (Shiny Trees), and set the fields to the correct responses.
Congrats, now run the map and watch as trees grow around the marine, and the closest tree turns pink!
Not a bad tutorial. The query persistent must be a new one since I played with them. You can have fun combining them with reference set event actions. Check my turret simulation demo map to see what I did with them (note was before HOTS).
Contribute to the wiki (Wiki button at top of page) Considered easy altering of the unit textures?
https://www.sc2mapster.com/forums/resources/tutorials/179654-data-actor-events-message-texture-select-by-id
https://media.forgecdn.net/attachments/187/40/Screenshot2011-04-17_09_16_21.jpg