Programming Quick Start

Create your first code project and add a new C++ class.

Windows
MacOS
Linux
Prerequisite Topics

This page assumes you have prior knowledge of the following topics. Please read them before proceeding.

ProgrammingQuickStartTopic.png

In this Quick Start Guide, you will learn how to setup a C++ project in the Unreal Engine and program your first C++ gameplay class in Visual Studio. By the time you've completed this tutorial, you will know how to do the following:

  • Create a new C++ Project

  • Create a new Actor class in C++

  • Edit that C++ class in your development environment, adding visual representation and functionality

  • Compile your project

  • Test your new Actor in the Unreal Editor

This guide assumes that you have already set up Visual Studio as your programming environment. If not, please refer to Setting Up Visual Studio for the Unreal Engine for instructions on how to install it and get it set up for programming with the Unreal Engine. We also assume that you have some familiarity with using the Unreal Editor before starting this guide, but for your convenience we will walk through all the steps necessary to create and manage C++ classes from the editor. The end product of this guide will be a cube that floats softly in mid-air and continually rotates, giving you a simple object to test as you learn to use the development environment for programming.

This guide assumes that you have already set up XCode as your programming environment. We also assume that you have some familiarity with using the Unreal Editor before starting this guide, but for your convenience we will walk through all the steps necessary to create and manage C++ classes from the editor. The end product of this guide will be a cube that floats softly in mid-air and continually rotates, giving you a simple object to test as you learn to use the development environment for programming.

1. Required Setup

Launch the Unreal Editor. When the Project Browser comes up, click the New Project tab, select the C++ tab, and then select the Basic Code template. Make sure that you have Starter Content enabled, choose your preferred Save Location and Name for this project, and then click Create Project. In our instance, we're naming our project QuickStart.

Click image for full size.

This will automatically create a simple, blank project with only essential C++ code in the solution, and it will automatically open inside both the Unreal Editor and Visual Studio. For more information on managing and creating Projects, please refer to the Project Browser page.

This will automatically create a simple, blank project with only essential C++ code in the solution, and it will automatically open inside both the Unreal Editor and XCode. For more information on managing and creating Projects, please refer to the Project Browser page.

Any Blueprint project can be converted to a C++ project. If you have a Blueprint project that you want to add C++ to, create a new C++ class per the next section, and the editor will set up your code environment for you. Also note that using a C++ project does not prevent you from using Blueprint. C++ projects simply set up the base classes for your project in C++ instead of Blueprint.

2. Create a New C++ Class

  1. In the Unreal Editor, click the File drop-down menu, then select the New C++ Class... command.

    Click image for full size.

  2. The Choose Parent Class menu will display. You can choose an existing class to extend, adding its functionality to your own. Choose Actor, as it is the most basic type of object that can be placed in the world, then click Next.

    Click image for full size.

  3. In the Name Your New Actor menu, name your Actor FloatingActor and click Create Class.

    Click image for full size.

    The Unreal Engine will automatically compile and reload with our new class selected in the Content Browser, and your programming environment will automatically open with FloatingActor.cpp.

3. Edit Your C++ Class

Now that we have created our C++ Class, we're going to switch over to Visual Studio and edit our code.

  1. In Visual Studio, locate the Solution Explorer, which by default is on the left side of the window, then use it to locate FloatingActor.h. In our project, it will be located under Games > QuickStart > Source > QuickStart.

    Solution Explorer

  2. Double-click FloatingActor.h to open it and bring it into focus in the text editor.

    Open Header File

    This is a header file. You can think of it as being sort of like a table of contents for a C++ class. Before we can start building any new functionality, we must declare any new Variables or Functions that we're using in this file.

  3. Add the following code underneath the declaration for AFloatingActor():

    UPROPERTY(VisibleAnywhere)
    UStaticMeshComponent* VisualMesh;

    Here we're declaring a StaticMeshComponent, which will act as our visual representation for our object. Note that it uses a UProperty macro, which makes it visible inside the Unreal Editor. For more information on UProperty and its specifiers, see the page on Properties.

  4. Now open FloatingActor.cpp and add the following code inside of AFloatingActor::AFloatingActor(), just before the closing bracket:

    VisualMesh = CreateDefaultSubobject<UStaticMeshComponent>(TEXT("Mesh"));
    VisualMesh->SetupAttachment(RootComponent);
    
    static ConstructorHelpers::FObjectFinder<UStaticMesh> CubeVisualAsset(TEXT("/Game/StarterContent/Shapes/Shape_Cube.Shape_Cube"));
    
    if (CubeVisualAsset.Succeeded())
    {
        VisualMesh->SetStaticMesh(CubeVisualAsset.Object);
        VisualMesh->SetRelativeLocation(FVector(0.0f, 0.0f, 0.0f));
    }

    This function is the constructor, and it tells the class how to initialize itself when it is first created. The code we have added will fill our VisualMesh reference in with a new StaticMeshComponent, attach it to our Actor, and set it to the cube mesh from the Starter Content assets. For more information about attaching components in code, refer to our guide for Creating and Attaching Components.

  5. Add the following code inside of **AFloatingActor::Tick(float DeltaTime), just before the closing bracket:

    FVector NewLocation = GetActorLocation();
    FRotator NewRotation = GetActorRotation();
    float RunningTime = GetGameTimeSinceCreation();
    float DeltaHeight = (FMath::Sin(RunningTime + DeltaTime) - FMath::Sin(RunningTime));
    NewLocation.Z += DeltaHeight * 20.0f;       //Scale our height by a factor of 20
    float DeltaRotation = DeltaTime * 20.0f;    //Rotate by 20 degrees per second
    NewRotation.Yaw += DeltaRotation;
    SetActorLocationAndRotation(NewLocation, NewRotation);

    The Tick function is where we add code that we want to execute in real-time. In this case, it will make our cube simultaneously rotate while also floating up and down. For more information about Ticking actors, see Actor Ticking.

Now that we have created our C++ Class, we're going to switch over to XCode and edit our code.

  1. In XCode, locate the Project Navigator, which by default is on the left side of the window, then use it to locate FloatingActor.h. In our project, it will be located under Games > QuickStart > Source > QuickStart.

    Solution Explorer

  2. Double-click FloatingActor.h to open it and bring it into focus in the text editor. This is a header file. You can think of it as a table of contents for a C++ class. Before we can start building any new functionality, we must declare any new Variables or Functions that we're using in this file.

  1. Add the following code underneath the declaration for AFloatingActor():

    UPROPERTY(VisibleAnywhere)
    UStaticMeshComponent* VisualMesh;

    Here we're declaring a StaticMeshComponent, which will act as our visual representation for our object. Note that it uses a UProperty macro, which makes it visible inside the Unreal Editor. For more information on UProperty and its specifiers, see the page on Properties.

  2. Now open FloatingActor.cpp and add the following code inside of AFloatingActor::AFloatingActor(), just before the closing bracket:

    VisualMesh = CreateDefaultSubobject<UStaticMeshComponent>(TEXT("Mesh"));
    VisualMesh->SetupAttachment(RootComponent);
    
    static ConstructorHelpers::FObjectFinder<UStaticMesh> CubeVisualAsset(TEXT("/Game/StarterContent/Shapes/Shape_Cube.Shape_Cube"));
    
    if (CubeVisualAsset.Succeeded())
    {
        VisualMesh->SetStaticMesh(CubeVisualAsset.Object);
        VisualMesh->SetRelativeLocation(FVector(0.0f, 0.0f, 0.0f));
    }

    This function is the constructor, and it tells the class how to initialize itself when it is first created. The code we have added will fill our VisualMesh reference in with a new StaticMeshComponent, attach it to our Actor, and set it to the cube mesh from the Starter Content assets. For more information about attaching components in code, refer to our guide for Creating and Attaching Components.

  3. Add the following code inside of **AFloatingActor::Tick(float DeltaTime), just before the closing bracket:

    FVector NewLocation = GetActorLocation();
    FRotator NewRotation = GetActorRotation();
    float RunningTime = GetGameTimeSinceCreation();
    float DeltaHeight = (FMath::Sin(RunningTime + DeltaTime) - FMath::Sin(RunningTime));
    NewLocation.Z += DeltaHeight * 20.0f;       //Scale our height by a factor of 20
    float DeltaRotation = DeltaTime * 20.0f;    //Rotate by 20 degrees per second
    NewRotation.Yaw += DeltaRotation;
    SetActorLocationAndRotation(NewLocation, NewRotation);

    The Tick function is where we add code that we want to execute in real-time. In this case, it will make our cube simultaneously rotate while also floating up and down. For more information about Ticking actors, see Actor Ticking.

4. Compile and Test Your C++ Code

  1. Save your work in both FloatingActor.h and FloatingActor.cpp. Then, in the Solution Explorer, right-click the project, click the Build command in the context menu, and wait for the project to finish compiling.

    PRQuickStart_4-1.png

    You should see a message that says "Succeeded" in the Output log at the bottom of the window.

    PRQuickStart_4-2.png

    Alternatively, you can go back to the Unreal Editor and click the Compile button in the toolbar at the top of the screen.

    PRQuickStart_4-3.png

    You should always save your work before attempting to compile, otherwise the changes you make in your code will not take effect.

  2. In the Unreal Editor, go back to the Content Browser, unfold C++ Classes, and then locate FloatingActor. It will be located in the folder that has the same name as your project, in our case, QuickStart.

    PRQuickStart_4-4.png

  3. Click and drag FloatingActor into the Perspective Viewport to create an instance of FloatingActor. It will be selected in the World Outliner as "FloatingActor1" and its properties will be visible in the Details Panel.

    PRQuickStart_4-5.png

    For more information about navigating the Viewport and placing Actors in the World, refer to the Level Designer Quick Start.

  4. In the Details Panel for FloatingActor1, set your Actor's Location to (-180, 0, 180). This will place it directly over the table in the default scene.

    PRQuickStart_4-6.png

    Alternatively, you can use the Move gizmo to move it there manually.

    PRQuickStart_4-7.png

  5. Press the Play In Editor button at the top of the screen.

    PRQuickStart_4-8.png

  1. Save your work in both FloatingActor.h and FloatingActor.cpp. Then, click the Product drop-down menu at the top of the screen, select the Build command, and wait for the project to finish building.

    PRQuickStart_Mac_4-1.png

    You should see a message that says "Succeeded" in the Output log at the bottom of the window. Alternatively, you can go back to the Unreal Editor and click the Compile button in the toolbar at the top of the screen.

    PRQuickStart_4-3.png

    You should always save your work before attempting to compile, otherwise the changes you make in your code will not take effect.

  2. In the Unreal Editor, go back to the Content Browser, unfold C++ Classes, and then locate FloatingActor. It will be located in the folder that has the same name as your project, in our case, QuickStart.

    PRQuickStart_4-4.png

  3. Click and drag FloatingActor into the Perspective Viewport to create an instance of FloatingActor. It will be selected in the World Outliner as "FloatingActor1" and its properties will be visible in the Details Panel.

    PRQuickStart_4-5.png

    For more information about navigating the Viewport and placing Actors in the World, refer to the Level Designer Quick Start.

  4. In the Details Panel for FloatingActor1, set your Actor's Location to (-180, 0, 180). This will place it directly over the table in the default scene.

    PRQuickStart_4-6.png

    Alternatively, you can use the Move gizmo to move it there manually.

    PRQuickStart_4-7.png

  5. Press the Play In Editor button at the top of the screen.

    PRQuickStart_4-8.png

5. End Result

You should now see your cube gently floating up and down over the table while it slowly rotates.

Congratulations! You've created your first Actor class entirely with C++! While this represents a very simple object and only scratches the surface of what you can do with C++ source code, you have at this point touched on all the essentials of creating, editing, and compiling C++ code for your game. You are now ready for more complex gameplay programming challenges, and we suggest a few below.

6. On Your Own!

Now that you know how to build a simple C++ Actor, try making it more configurable. For instance, you can add variables to control its behavior:

In FloatingActor.h:

...
public: 
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="FloatingActor")
    float FloatSpeed = 20.0f;

    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="FloatingActor")
    float RotationSpeed = 20.0f;
...

In FloatingActor.cpp:

...
NewLocation.Z += DeltaHeight * FloatSpeed;          //Scale our height by FloatSpeed
float DeltaRotation = DeltaTime * RotationSpeed;    //Rotate by a number of degrees equal to RotationSpeed each second
...

By adding these variables in the header and replacing the float values we were using to scale DeltaHeight and DeltaRotation in the .cpp, we can now edit the float and rotation speed in the Details Panel when we select our Actor.

PRQuickStart_6-1.png

You can experiment by adding other kinds of behavior to the Tick function using Location, Rotation, and Scale.

You can also try attaching other kinds of components in C++ to create a more complex object. Refer to the Creating and Attaching Components guide for examples of different types of components you have available, and try adding a Particle System Component to add a bit of flare to your floating object.

PRQuickStart_6-2.png

Finally, if you right-click your own Actor class in the Content Browser, you will find the option to extend it, either in C++ or in Blueprint, enabling you to create new variations of it.

PRQuickStart_6-3.png

You can have a whole library of FloatingActors, each substituting different Meshes or parameters as you so choose.

PRQuickStart_6-4.png

Sample Code

FloatingActor.h

// Copyright 1998-2019 Epic Games, Inc. All Rights Reserved.

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "FloatingActor.generated.h"

UCLASS()
class QUICKSTART_API AFloatingActor : public AActor
{
    GENERATED_BODY()

public: 
    // Sets default values for this actor's properties
    AFloatingActor();

    UPROPERTY(VisibleAnywhere)
    UStaticMeshComponent* VisualMesh;

protected:
    // Called when the game starts or when spawned
    virtual void BeginPlay() override;

public: 
    // Called every frame
    virtual void Tick(float DeltaTime) override;

};

FloatingActor.cpp

// Copyright 1998-2019 Epic Games, Inc. All Rights Reserved.

#include "FloatingActor.h"

// Sets default values
AFloatingActor::AFloatingActor()
{
    // Set this actor to call Tick() every frame.  You can turn this off to improve performance if you don't need it.
    PrimaryActorTick.bCanEverTick = true;

    VisualMesh = CreateDefaultSubobject<UStaticMeshComponent>(TEXT("Mesh"));
    VisualMesh->SetupAttachment(RootComponent);

    static ConstructorHelpers::FObjectFinder<UStaticMesh> CubeVisualAsset(TEXT("/Game/StarterContent/Shapes/Shape_Cube.Shape_Cube"));

    if (CubeVisualAsset.Succeeded())
    {
        VisualMesh->SetStaticMesh(CubeVisualAsset.Object);
        VisualMesh->SetRelativeLocation(FVector(0.0f, 0.0f, 0.0f));
    }
}

// Called when the game starts or when spawned
void AFloatingActor::BeginPlay()
{
    Super::BeginPlay();

}

// Called every frame
void AFloatingActor::Tick(float DeltaTime)
{
    Super::Tick(DeltaTime);

    FVector NewLocation = GetActorLocation();
    FRotator NewRotation = GetActorRotation();
    float RunningTime = GetGameTimeSinceCreation();
    float DeltaHeight = (FMath::Sin(RunningTime + DeltaTime) - FMath::Sin(RunningTime));
    NewLocation.Z += DeltaHeight * 20.0f;       //Scale our height by a factor of 20
    float DeltaRotation = DeltaTime * 20.0f;    //Rotate by 20 degrees per second
    NewRotation.Yaw += DeltaRotation;
    SetActorLocationAndRotation(NewLocation, NewRotation);
}
Select Skin
Light
Dark

Welcome to the new Unreal Engine 4 Documentation site!

We're working on lots of new features including a feedback system so you can tell us how we are doing. It's not quite ready for use in the wild yet, so head over to the Documentation Feedback forum to tell us about this page or call out any issues you are encountering in the meantime.

We'll be sure to let you know when the new system is up and running.

Post Feedback