[JAVA] Detailed explanation Actor (libGDX)

Development with libGDX often uses a class called Actor, or a subclass of Actor. Let's examine this class again.

Premise

Scene2D in general. I think that the person who called this article by shinsan68k can understand what I researched and wrote.

Basics of libGDX 5 Using Scene2D by shinsan68k

What is an Actor

Actor is one of the components of libGDX's function called Scene2D for making 2D games. Well, in fact, it's a Java class.

An Actor is a node in the Scene2D scene graph (a tree structure of all objects placed in space) and has a hierarchical structure. You can create a hierarchical structure with a subclass of Actor that can contain an Actor called Group.

image)

For example, if you think about it in the image below, you can think of lids, bottles, beverages inside, labels, etc. as actors. The Group is a group that combines these into a single bottle of sake. Group is also a subclass of Actor, so it can be said to be a type of Actor.

Illustration of sparkling sake-Irasutoya

Here's a very simplified source code. (Actually, it is necessary to add the corresponding image, adjust the position, adjust the size, etc.)


package sample;
import com.badlogic.gdx.scenes.scene2d.Actor;
import com.badlogic.gdx.scenes.scene2d.Group;

/**
 * Created by yy_yank on 2017/01/22.
 */
public class SparklingNihonsyu extends Group {

    public SparklingNihonsyu() {
        init();
    }

    public void init() {
        Actor cap = new Actor();　//lid
        Actor bottle = new Actor(); //bottle
        Actor label = new Actor(); //label
        Actor sparklingAlcohol = new Actor(); //Sake
        addActor(cap);
        addActor(bottle);
        addActor(label);
        addActor(sparklingAlcohol);
    }
}

If you add this Sparkling Nihonsyu to an Actor in another place, these Actors will be added to the scene graph, and you will be happy to be able to display sake anywhere. Actor (or Group) is used like that.

Have you ever used Photoshop, GIMP, or any other paint tool that can handle multiple layers like that? Group is close to that layer.

The great thing about Group is that the size change applied to Group is applied to all Actors of child elements. Therefore, if you use setScale (0.5f) for sake sparkling, you can keep the image magnification of the bottle, label, and lid.

Class field of Actor

position (x, y), rectangular size, origin (originX, originY), scale (scaleX, scaleY), rotation, color (default is new Color (1, 1, 1, 1)), parent Other private fields

Method of Actor

All as if you had a look at the javadoc. .. Class Actor

Life cycle system

draw

It is a drawing method, but it is an empty implementation

Called when updating the Actor. Note that it is called every frame.

Returns an instance of itself when touched within the drawn x, y coordinates of the Actor

State operation

remove

Erase yourself from the scenegraph

addListener
removeListener

Add / remove event listeners

addAction
removeAction

Add / Remove Action

getActions

Returns an array of all registered

hasAction

Whether you have Action

clearActions

Delete the registered Aciton

clearListeners

Delete the registered listener

Remove all Listeners

clear

Delete registered Action and Listener

Status notification system

positionChanged
sizeChanged
rotationChanged

Since it is protected, if you override it, you will be notified when each state changes

Coordinate conversion system

screenToLocalCoordinates

Converts from screen coordinates to Actor's local coordinates. The tree structure is recursively called from Stage to the Actor (Stage coordinates → Actor instance 1 local coordinates → Actor instance 2 local coordinates ... → Actor instance N local coordinates

stageToLocalCoordinates

Unlike screenToLocalCoordinates, the coordinate conversion is started from the parent of the Actor who called this method.

localToStageCoordinates

Converts the local coordinates of the Actor to the coordinates of the Stage. It's the opposite of screenToLocalCoordinates. It propagates from the child to the parent.

localToParentCoordinates

This method converts the coordinates of the actor to the coordinates of the parent one level above.

localToAscendantCoordinates

It is used when you want to know the coordinates of a specific Actor. Coordinate conversion from the current Actor to the specified Actor.

parentToLocalCoordinates

Called when converting coordinates from a parent element to a child element Actor. Looking at the implementation, it seems that it is supposed to be called when converting from Stage (root) to Actor.

Two-phase event

There are two types of events that Actors have. The capture phase and the normal phase.

Capture phase

It may be helpful to describe the capture phase as an interceptor before the event is notified.

It is used when the parent handles and cancels the event before the event occurs in the following flow.

Stage → Actor 1 → Actor 2 → Actor where the event occurs

Normal phase

The normal phase is a really common click event. In this case, event handling is possible only for the actor in which the event occurs. In addition, the direction of the arrow is reversed and the propagation is such that it climbs from the Actor to the Stage (that is, the route).

Stage ← Actor 1 ← Actor 2 ← Actor where the event occurs

Considering which one to use, I think there are more listeners in the normal phase. However, it seems that a mechanism can be created well by using the capture listener as needed.

Listener stop and cancel

The listener event provides stop and cancel methods. stop = stop propagation cancel = Cancel propagation and make no processing (rewind)

In other words, the flow as described above stops. This seems to be both capture / normal phase.

//Capture phase. Not transmitted to Actor2
Stage → Actor 1 → stop!!→ x Actor 2 → Actor where the event occurs

//Normal phase. Not transmitted to Actor2
Stage ← Actor 1 ←　Actor 2 x ← stop!!← Actor where the event occurs

Scene2D scope

Considering the scope of Scene2D (which may include the whole libGDX) Application = Application scope Stage = Session scope Actor = View scope I think it feels like that.

Actor is an expanded interpretation. It depends on the scale of the actor, and it's a fairly abstract class, so I don't think I can say it. If you think of it as a screen or a component, I think it's not out of place.

Application is an interface called com.badlogic.gdx.Application. It manages the information and life cycle of each platform. ApplicationListener or ApolicationAdapater is specialized only for the life cycle called from Application, and I think that a class called XXXGame will be created with gdx-setup.jar, but if it is a class implemented think.

Stage is the root element of the Scene2D tree structure that bundles Actors. It handles input events and so on.

Advantages and disadvantages of Actor

What are the strengths and weaknesses?

There is such an exchange in stack overflow.

When to use actors in libgdx? What are cons and pros? - stack overflow

It seems that it is a story about when to use Actor, starting from what to do with Stage and Actor properly.

Pros

Actor can use Action

You can easily implement animations and effects using the Actions class

Grouping is possible in Group

Actors can be grouped and used on each screen or component

Easy to test hit and touch events

When using Stage hit, it always returns the first Actor (with Actor) that implements the hit method. The Actor iterates to find the hit method and returns null if not found.

hit is used as a method of Stage, but in the touch event of Actor, the local coordinates of Actor are passed from Stage.

Stage also wraps and handles objects. For example, to prevent other actors from receiving the touchDown event, only the Actor with the event is notified, and the other Actor contained in the Actor is stopped without notifying the touchDown event. At the same time, the Actor who was notified of the event is focused.

Disadvantages

Always need Stage. Even if it's a limited feature.
Many people use other things such as box2d instead of Actor when creating logic to control the state of the game.
Adopting an Actor probably requires two stages, the UI Stage and the game world Stage. If you're not using it, you're probably doing something with Sprite Batch and Camera. → This seems to be about UI state management and game state management.
Remember that the Actor's draw method is an empty implementation and must always be managed by the implementer. You will have to have a TextureRegion or Sprite as a class field
If you want to mess with the drawing update logic, you need to override act

I think it's quite important to manage the UI status and the game status. Also, since Stage is the root, it will depend on Stage to inquire information.

Difference between Actor and Sprite

Another is stack overflow material.

libgdx difference between sprite and actor

What is the difference between Sprite and Actor? So that's it.

Sprite

Sprite is an Image.
2D drawing is possible with Low Level API
Has position, size and rotation
Can be drawn with Sprite Batch etc.

Actor

Part of the scene graph of scene2d
High Level API
You can adjust the position of the image in the scene graph (you can adjust it not by the absolute position of the screen but by the relative position in the Actor. I think it is also called local coordinates).
The route is Stage and the Stage itself is not displayed
Stage is a container for Actors
The screen can be systematized by Actor
Stage → Actor pass down through of Input event is excellent (I think that it is converted to local coordinates when the scene graph is propagated from Stage to Actor in order)
Stage knows when the Actor was drawn
Note that the Actor does not have a Texture like Sprite
If you use it instead, it would be an Image class (a class that has Sprite in a plain Actor)
Another way is to use a subclass of Actor such as Text.

When you touch libGDX for the first time, it will be a single screen, and the UI configuration will be very simple, so you can just use Sprite, right? You don't need an actor, right? It tends to be, but the answer to that is good.

This kind of comparison is a learning experience.

General-purpose UI classes such as the Text class are provided in scene2d.ui. https://github.com/libgdx/libgdx/wiki/Scene2d.ui

Summary

I wrote it ramblingly, but I will summarize it briefly.

Scene2D has a scene graph rooted at Stage
Actor is a component of Scene2D, so it is one of the nodes of the scene graph.
Actors can be nested
Actor has no drawing function (empty implementation)
X and Y coordinate conversion is performed between Stege-Actor and Actor-Actor.
There is a capture / normal phase event between Stege-Actor and Actor-Actor
If you want to use a UI that inherits a general-purpose Actor, it is prepared in scene2d.ui.