Unreal Engine 4 Plugin quick start

Overview and Beta
Check out the SkookumScript Unreal Engine 4 Plugin landing page for an overview.
Sign up for the SkookumScript UE4 Plugin beta to get the latest beta release.

Installation

If you haven’t installed the plugin yet, please check out the installation page on our forum! It will guide you through the process then redirect you back here.

Unreal Editor settings

Before getting started with the SkookumScript Unreal Engine 4 Plugin, you should toggle a few settings in the Unreal Editor for a better experience. These changes will let Unreal run at full fidelity, even when the input focus is on the SkookumScript IDE. This will use more CPU, but the experience with SkookumScript will be much better.

  • In the Unreal Editor menu select EditEditor Preferences...
  • In that dialog ensure that GeneralMiscellaneousPerformanceUse Less CPU When In Background is unchecked.
  • Also make sure in the same dialog that Level EditorSoundAllow Background Audio is enabled.

This assumes that all other settings are the defaults. There are many more Unreal Editor settings—don’t be afraid to tinker with anything that looks interesting.

First step: SkookumScript as turbo-charged command console

If you are not yet familiar with the IDE + command console, this quick video will introduce you to its core features.

Right after installation, you can immediately start using the SkookumScript IDE as a power console that is deeply integrated into the Unreal Engine and allows you to query and manipulate just about anything you like. Right out of the box, 1100+ classes and structs with 3300+ methods and 5300+ member variables are at your fingertips to make awesome things happen.

Using SkookumScript as a command console does not require your project to use SkookumScript for gameplay scripting. The command console will work with any UE4 project!

For example:

  • to get an actor’s transform, simply run Actor.named("MyActor").transform
  • to make a pawn navigate to the player, use Pawn.named("MyActor")._path_to_actor(player_pawn)

We recommend starting out by carefully studying the example code listed in the IDE’s workspace window and executing some of the expressions/commands by placing the caret on a line and pressing F4. Expressions can be as simple as 4+5 or as sophisticated as executing an entire program via a language feature called closures.

Running script snippets will become an integral part of your workflow—and everyone on your team will love it.

Next step: SkookumScript-enable your project

After familiarizing yourself with SkookumScript by playing with the console you might decide that you’d like to permamentily add some SkookumScript code to your project.

You can easily accomplish this from the IDE by simply attempting to add a new SkookumScript class, method, coroutine or data member to your project. For example, select the Master class in the class tree view, then click on the little + icon on the bottom left of the class hierarchy tree view (or choose New Class / Member... from the File menu or press CTRL-N).

The IDE will then ask if it’s ok to store your scripts and compiled binaries inside the project folder.

When you agree, SkookumScript will set up a new folder Scripts inside your project folder that will contain your project-specific scripts, as well as a folder skookumscript inside your Content folder which will contain the compiled binary version of your project scripts. The DefaultEngine.ini of your project will also be modified to ensure the compiled binaries will properly “cooked” when you package your game for release.

Your project is now SkookumScript-enabled and you can add new methods to existing classes or even whole new classes!

Make sure you understand the concept of overlays which help you to organize your project scripts properly (see IDE documentation).

SkookumScript-aware actors

As mentioned above, you can use SkookumScript to run code on any UE4 actor, for example from the console. However sometimes you also want to run special code whenever a particular type of actor gets spawned, or when it gets destroyed, or you want to store SkookumScript variables in an actor.

You accomplish this by associating that type of actor with a SkookumScript class via the SkookumScriptComponent. For example, if you have an Enemy actor that you’d like to add SkookumScript abilities to, open up the Enemy Blueprint, and in the components tab, choose Add Component. Choose the SkookumScriptComponent.

By default, a SkookumScript class is automagically generated for each Blueprint class. So if the name of your actor’s Blueprint is Enemy then there already is a SkookumScript class Enemy that is associated with it. Now that you added a SkookumScriptComponent to your Enemy Blueprint, the default constructor ! (if present) of the class Enemy will be called whenever an actor of type Enemy gets spawned, and the destructor !! (if present) will be called upon its destruction. You can also add member variables to the class Enemy which will be stored in each instance of your Enemy actor.

You can also extend the UE4/Blueprint class hierarchy with SkookumScript-only classes. E.g. in the case of the Enemy actor class you can create a class EnemyCaptain that is derived from Enemy and inherits most of the Enemy class’ functionality, but overrides a few methods that do things differently. In this case, you could select a particular actor in the World Outliner, select its SkookumScriptComponent and set the parameter Script Class Name to EnemyCaptain. Now, this particular actor will be known to SkookumScript as an object of type EnemyCaptain while all other actors derived from the Enemy Blueprint will be of type Enemy.

Mind actors

If you haven’t yet, familiarize yourself with the concept of Minds in SkookumScript. Minds are used to control coroutines, and encapsulate logical components of gameplay (levels, missions, minigames, squad AI, group behaviors etc.).

You can instantiate a SkookumScript Mind in a UE4 game by attaching it to an actor using a SkookumScriptComponent as described in the previous chapter. Simply enter the name of your Mind-derived class into the Script Class Name parameter of the SkookumScriptComponent, and an instance of your class will be automatically created and attached whenever that UE4 actor is spawned.

One application is for example a “Level Mind”: Place an empty actor in your level and name it “Level Mind”. Add a SkookumScriptComponent and set the Script Class Name to the name of your Mind class. Your Mind will now be instantiated when that level is loaded, and destroyed when the level is unloaded.

Call SkookumScript methods and coroutines from Blueprint event graphs

SkookumScript allows you to combine script methods and coroutines in many different ways with Blueprint event graphs, allowing you to get the best out of both systems.

To expose a SkookumScript method or coroutine to the Blueprint event graph system, prefix its declaration with the annotation &blueprint like in the following example (handle_gamepad_look_up() method in the class Pawn):

&blueprint
(Real look_up_rate, Real base_look_up_rate) 
  [
  add_controller_pitch_input(look_up_rate * base_look_up_rate * GameLib.world_delta_seconds)
  ]

Then, recompile its SkookumScript class (or, the entire project) which will make it available for placement in your event graph. Right click in your graph, and select the method you just exposed to Blueprints.

Place it in your graph, and connect it just like you would any other node.

Now, whenever its execution pin gets triggered, the SkookumScript method is invoked and its return value (if any) passed to the output pin.

Coroutines can be declared and placed in much the same way. There are two differences though:

  • triggering the node’s execution pin will begin executing the coroutine, however it may finish many frames later
  • coroutines do not have a return value

Coroutine nodes always trigger the outgoing execution pin immediately, regardless of the time it takes for the coroutine to terminate. If you would like something to happen in the graph when the coroutine finishes, use event nodes as described in the next section.

Trigger Blueprint events with SkookumScript methods

You can also trigger execution of Blueprint event graph nodes from SkookumScript via a Blueprint event node exposed from SkookumScript.

To create a Blueprint event, create a method declaration prefixed with the &blueprint annotation, but without a body.

&blueprint
(Boolean some_parameter) 

Again, recompile its SkookumScript class (or, the entire project) which will make it available for placement in your event graph. Right click in your graph, select Add Event, then, in the Skookum Script category, select the method you just exposed to Blueprints. Place it in your graph, and connect its output pins just like you would any other Blueprint event.

Now, whenever your SkookumScript method is called from a script, its arguments are passed to the event node’s output pins, and the event node’s execution output pin is triggered!

Use UE4 delegate events to control SkookumScript program flow

UE4 allows game objects to “listen” to events happening in the world. We have implemented the most commonly used events using coroutines and closures. Here is example code from our demo project:

Volume.named("TriggerBerzerk")._wait_begin_overlap

This code waits for an ActorBeginOverlap event on the “TriggerBerzerk” volume. The volume is only reachable by the player pawn so in this case there is no need to check which kind of actor triggered it.

If you wanted to make sure only the player pawn (of class Hero) satisfies the waiting condition, the statement could be modified as follows:

Volume.named("TriggerBerzerk")._wait_begin_overlap(Hero)

You can also repeatedly execute code whenever a delegate event occurs (this coroutine will run forever until its Mind is destoyed):

player_pawn._on_take_any_damage_do[player_pawn.draw_text("Ouch")]

You can also process events until you find one that you like, then proceed with execution of the current coroutine:

Volume.named("TriggerBerzerk")._on_begin_overlap_do_until[actor.class_of?(Hero)]

Simple example scripts

Take a look at the script examples in the Workspace Window (REPL) to get some ideas. We will add more examples here in the future.

See the Workspace Window (REPL) for more examples.

Enjoy!