Dolly Pro

💡

This documentation was adapted by community user Collin based on the original Chinese documentation for Arkos by the author.

Arkos Cocrea account: https://cocrea.world/@Arkos

Dolly Pro usage

Dolly Pro is an upgraded version of the original Dolly extension, designed to facilitate all tasks related to clones! For example:

Enable data interaction between clones: read and modify the health of a clone with a specific ID.
Determine which clone is being interacted with. For instance, detect which enemy is hit by a bullet and deduct the corresponding health.
Specify the ID of a clone during cloning (e.g., set a clone's ID as 'Player').

Before cloning, preset the clone data (when cloning the original Dolly, only one data item was supported).

Clone Grouping System (Clones can be added to a group. A clone can be added to multiple groups. After joining a group, unified operations can be performed on the clones in a group.)

Detection Blocks: For example, detecting the nearest enemy; getting the ID of the enemy hit by a bullet.

Motion Blocks: Previously, making one clone face another clone (e.g., making a turret face the nearest enemy clone in a tower defense game) was a very challenging problem. In addition, calculating the distance and direction between clones was equally tricky. Now, with Dolly Pro, these complex functions can be accomplished with just one block.

With Dolly Pro, you can pretty much say goodbye to the original Dolly!

Detailed Introduction to Dolly Pro Blocks

🔧 Common Tools

Determine if Self is Clone or Original: This block is primarily used for broadcast-related blocks. Since clones also receive broadcasts, it's essential to check if the receiver is the original, ensuring only the original handles the broadcast.

For example: the code on the left below would cause clones to receive the broadcast and clone themselves, so you need to add a check to ensure only the original sprite executes to avoid redundant cloning.

Get the Number/ID List of All Clones of a sprite: The ID list is returned in JSON format, such as ["Clone ID1", "Clone ID2", ...].

Get the ID of a sprite:

💡

Concept: What is an ID? An ID is a unique identifier for a clone or sprite, akin to a "code name" (usually a string of sprites). IDs are used to represent a clone/sprite, allowing operations to be performed on a specific clone/sprite by its ID. (Similar to how the uses IDs to represent users, e.g., Arkos’s ID is 203945102.) Why use IDs instead of names? Names can be duplicated; for example, there can be many users named "Arkos" in the community, but only one Arkos with ID 203945102. Similarly, the uniqueness of clone IDs ensures that a clone can be represented and manipulated accurately by its ID.

🔔 Event Blocks

When a sprite is Cloned/Deleted: Triggers when a sprite is cloned or a clone is deleted (similar to a broadcast).

For example:

Because the usage is similar to a broadcast, a check is typically required to ensure only the original sprite handles it (otherwise, clones will also execute it).

Right Before a Clone Starts/Deletes: Triggers right before a clone starts or right before a clone is deleted (triggered only by the clone itself, similar to "when the clone starts"), which can be used for initializing actions for the clone and cleanup actions when the clone is deleted.

In the original version, if we initialize a clone in one script, other scripts must "wait 0 seconds" to avoid actions being executed before initialization is complete:

Now, we can write it like this:

Similarly, sometimes we want to perform some cleanup actions before a clone is deleted, which requires adding code at every point where the clone is deleted, making it very cumbersome:

Now, we can write it like this to achieve unified handling before a clone is deleted:

💡

Note: Do not write it like this ↓ as it may cause a loop deletion bug! (Although Dolly Pro has protective measures for this writing style, it is best to avoid it to prevent some peculiar bugs.)

Send/Receive Private Messages: Can be understood as targeted private broadcasts, allowing messages to be sent specifically to a certain clone (or a group of clones). Only the designated recipient can receive the message; others cannot.

For example, sending a private message "Rally to me" to the group of clones classified as "Allies" will cause the clones in that group to move towards the sender of the message:

Additionally, a private message can include specific content. For instance, sending a "Attack" private message can include the ID of the target to be attacked:

Clone and Delete Blocks

Preset the data for the next clone’s x / y / size, etc.

For example, set the coordinates and direction for the next clone to be created:

Preset key-value data for the next clone: This data is somewhat like the "private variables" of a clone, but you can freely name them.

For example, attach a "speed" data to a "bullet":

Preset the group(s) the next clone will join: Set the group(s) that the clone about to be created will join (it can join multiple groups).

Clone and specify an ID: While cloning, set the ID for the clone. The specified ID can be left blank, meaning no ID is specified, and the clone will have the same effect as the original, using a random ID.

💡

Note: The specified new clone’s ID must not duplicate an existing clone’s ID; otherwise, the ID setting will fail, and the new clone will use a random ID. By specifying an ID, we can give clones "code names." For example, set the player's clone ID to "player," and then it will be easy to access this clone using the ID "player":

ID of the just cloned clone: Save the ID of the just cloned clone.

For example, the following code is actually equivalent: (Note: The right side clones first and then sets, but it is essentially setting before the clone executes the actual actions. Cloning only creates the clone first; the clone has not performed any actual actions yet.)

Delete the clone with the specified ID.

Determine whether a clone with the specified ID exists.

📄 Information Retrieval Blocks

Get my ID and other information: Used to get the current clone's ID and other information.

Read and modify my information: Used to read and modify the key-value pair information of the current clone/sprite (similar to private variables, but data is accessed by directly entering the name).

💡

Note: The preset data is this kind of key-value pair data (equivalent to data set in advance before cloning).

Read and modify data of a clone with a certain ID: Based on the ID, read/set the information of a specific clone to achieve data interaction between clones.

Set the x/y/size and other information of a clone with a certain ID: Note: This block is hidden by default and needs to be enabled by clicking the "Show Hidden Blocks" button.

📁 Clone Group Blocks

Add/remove clones to/from a group: Used to add or remove a clone/sprite to/from a clone group (Note: A clone can belong to multiple groups at the same time. For example, it can belong to both the "Enemies" group and the "Entities" group. When a clone is deleted, it will automatically be removed from the group).

Determine if a clone belongs to a group: Check if a specific clone belongs to a particular group.

Number of clones in a group / IDs of clones in a group: Get the number of clones in a group and the ID of the nth clone in the group.

Import the ID list of a group into a list: Overwrite a list with the ID list of a group or add the group’s ID list to the end of the list.

Iterate through each clone in a group: Iterate through each clone in a specific group. (Note: This block is hidden by default and needs to be enabled by clicking the "Show Hidden Blocks" button.)

For example, the writing style on the left in the image below can be simplified into the writing style on the right:

💡

Note: Currently, all C-shaped blocks in Gandi extensions (including the above block) do not support compile mode. Using them in code may cause the script to fail to compile and may slow down the performance of compile mode, so use them with caution.

🔍 Detection Blocks

Get the ID of the nearest/farthest clone in a group: Used to get the ID of the closest/farthest clone in a specific group relative to oneself. For example, AI can find the nearest enemy, or in a tower defense game, a turret can find the nearest enemy.

Determine if a clone collides with a clone of a specific ID/group: Used to check if a clone collides with a specific clone or a clone in a certain group.

For example, to check if it collides with the original sprite 1:

Get the ID of the clone from a group that it collided with: For example, a bullet can get the ID of the enemy it collided with. You can choose to get the ID of one of the clones it collided with or get the IDs of all collided clones. When getting all, it returns a JSON list in the form: ["Clone1", "Clone2", ...].

Import the ID list of collided clones from a group into a list: Import the IDs of all collided clones into a list for further processing.

Determine if a clone collides with a point (x, y): Check if a clone collides with a point (note: this block is hidden by default).

This can be used for simplified hitbox detection, such as determining if a point falls on an obstacle.

Get the ID of the topmost clone at a point (x, y): Get the ID of the topmost clone at a specific point (note: this block is hidden by default).

For example, in a card game, check if a card is the topmost one at the mouse position (not covered by other cards):

🚶 Motion Blocks

Calculate the distance/direction/angle difference to a clone: Used to calculate information such as the distance to a specific clone.

The options are defined as follows:

Direction: The direction from the current clone's position to the other clone's position.
Angle difference (positive): The remaining angle the current clone needs to rotate to face the target clone.
Angle difference (signed): The remaining angle the current clone needs to rotate to face the target clone. If rotating counterclockwise, the angle difference is negative; if rotating clockwise, the angle difference is positive.

Calculate the distance/direction/angle difference between two clones: Calculate data such as the distance between two specified clones.

Face/move to a clone: For example, in a tower defense game, make a turret face a specific enemy.

Rotate/move towards a clone: Move a certain distance or rotate a certain angle towards a clone. For example, in a tower defense game, rotate the turret 10° towards the enemy (note: if the distance/angle difference is less than the speed/rotation speed, it will move directly to/face the target).

🚧 Experimental Blocks (These blocks are hidden by default)

Modify your own ID: Change the ID to a specified ID. (After modifying the ID, the ID information in the clone group will also be updated.)

This block is mainly used to change the sprite’s ID, for example, directly setting the sprite "player" ID to "player" for easier manipulation.

💡

Note:

If the ID to be changed already exists, the modification will fail, and the original ID will still be used.
If other parts of the code store the old ID of this sprite/clone, after changing the ID, the old ID will not be updated, and the sprite cannot be accessed through the old ID. Therefore, use this block with caution unless you are sure that other parts of the code do not store the old ID of this sprite.

Coordinate and direction access transfer block: This block is relatively difficult to understand and may have limited use cases. Its function is to transfer all access to the clone’s x coordinate, y coordinate, and direction in the Dolly Pro extension to access key-value pair data with specified names. (For example, if you fill in the parameters “x”, “y”, and “direction”, then access to the sprite’s coordinates and direction will be transferred to accessing key-value pair data with these names) (the direction can be left blank, which means the clone's direction will still be directly accessed).

The main application scenario for access transfer is, for example, when making a 3D game, calculating the distance between two clones no longer uses the original Scratch coordinates but instead stores the coordinate data in key-value pairs and calculates the clone distance based on the key-value pair data.

Cancel coordinate and direction access transfer: Used to cancel the access transfer effect of the above block.

💡

If you have any questions or suggestions, you can find us in the discord server: https://discord.gg/U3nyveCvRa