Scripting Introduction

This introduction will run you through how to create your first Actor class in script, and how to interact with it in unreal and blueprint.

Setup

Make sure you have the following set up:

See the Installation page for details.

Starting the Project

Creating the Actor Class

Within Visual Studio Code, create a new file and call it IntroductionActor.as.

Files with the .as extension placed under your project's Script/ folder are automatically loaded by the angelscript plugin.

Inside IntroductionActor.as, let's declare a new Actor class:

class AIntroductionActor : AActor
{
}

We've now created our first scripted Actor!

Placing the Actor in Unreal

Immediately after hitting "Save" on our script file, it should become available within the unreal editor.

Adding Functionality to the Actor

We have a totally empty actor in the level now with no functionality. As an example, let's make this actor perform a configurable countdown:

class AIntroductionActor : AActor
{
    UPROPERTY()
    float CountdownDuration = 5.0;

    float CurrentTimer = 0.0;
    bool bCountdownActive = false;

    UFUNCTION(BlueprintOverride)
    void BeginPlay()
    {
        // Start the countdown on beginplay with the configured duration
        CurrentTimer = CountdownDuration;
        bCountdownActive = true;
    }

    UFUNCTION(BlueprintOverride)
    void Tick(float DeltaSeconds)
    {
        if (bCountdownActive)
        {
            // Count down the timer, and
            CurrentTimer -= DeltaSeconds;

            if (CurrentTimer <= 0.0)
            {
                // The countdown was complete!
                // Print a message to the screen
                Print("Countdown was completed!");
                bCountdownActive = false;
            }
        }
    }
}

Some of the important things that are happening here:

Now, if you play the level the actor is placed in and wait 5 seconds, you will see the message appear:

Adding Components to the Actor

Right now, our Actor is still empty of any components, and only implements some functionality on tick.

Let's add some components to it! We want a Scene Component as the root, and then attach a Static Mesh Component and a Billboard Component to it.

Add the following at the top of your actor code:

class AIntroductionActor : AActor
{
    UPROPERTY(DefaultComponent, RootComponent)
    USceneComponent SceneRoot;

    UPROPERTY(DefaultComponent, Attach = SceneRoot)
    UStaticMeshComponent Mesh;

    UPROPERTY(DefaultComponent, Attach = SceneRoot)
    UBillboardComponent Billboard;

....

When you save your script file, you should see the new components appear on the Introduction Actor you've placed in the level.

You can read more about adding components on the Actors and Components page.

Tip: Clicking one of the "Edit in C++" links in the components menu will jump your Visual Studio Code to the place the component is added in your script.
The angelscript plugin often hooks into Unreal's normal C++ functionality, so script classes behave like C++ classes in many ways.

Creating a Blueprint Actor

The actor now has a Static Mesh Component, but we can't see it because no Static Mesh has been chosen on it!

We could of course select the actor in the level and choose one, but we don't want to do that for each actor we place individually.

Instead, let's create a Blueprint of our new introduction actor:

Calling in and out of Blueprint

Now that we have a blueprint, we can change the script to work together with its node graph:

In our IntroductionActor.as, change the script code for its BeginPlay and Tick functions to this:

    UFUNCTION(BlueprintOverride)
    void BeginPlay()
    {
        // We no longer start the countdown on BeginPlay automatically
    }

    UFUNCTION()
    void StartCountdown()
    {
        // Start the countdown when StartCountdown() is called
        CurrentTimer = CountdownDuration;
        bCountdownActive = true;
    }

    /**
     * Declare an overridable event so the actor blueprint can
     * respond when the countdown finishes
     */
    UFUNCTION(BlueprintEvent)
    void FinishedCountdown() {}

    UFUNCTION(BlueprintOverride)
    void Tick(float DeltaSeconds)
    {
        if (bCountdownActive)
        {
            // Count down the timer, and
            CurrentTimer -= DeltaSeconds;

            if (CurrentTimer <= 0.0)
            {
                // The countdown was complete!
                // Print a message to the screen
                Print("Countdown was completed!");
                // Also: trigger a blueprint event
                FinishedCountdown();
                bCountdownActive = false;
            }
        }
    }

After saving this change, we can now open BP_IntroductionActor, and add nodes like this:

Now, the blueprint must specifically start the countdown, and when the countdown is finished the blueprint will automatically destroy the actor.

If you play the level with the blueprint placed, you will see it disappear after 5 seconds.

Script Examples

The UnrealEngine-Angelscript project contains a Script-Examples/ folder.
Here, you can find more detailed example scripts that you can read or copy to your project.

Further Reading

More documentation is available on this website in the sidebar to the left.

We recommend reading through at least the "Script Features" pages to get an overview of what can be done in scripts.

Some good starting points are: