Core API Documentation

Up until this lesson, you have learned how to use Lua, a versatile language with many different applications. To use Lua in Core, we will also need a set of objects and functions created for the platform, which are all part of the Core API.

API

What an API is

API stands for Application Programming Interface, and is a set of useful objects and functions that allow you to operate a tool. In this case, the tool that you are driving is the Core platform.

The makers of Core created a game development system, and then created the functions that you could use to make your game.

You can still create your own variables and functions, but these are designed to specifically work with the kinds of things you find in Core, like players, 3D objects, and sound and visual effects.

How to Read the API Documentation

Start by going to https://docs.coregames.com/api/ to see the complete list of all the object types in Core, and what you can do with each of them.

When you are deciding how to approach a programming solution, follow these steps.

1. Think about the type of object you are using
2. Look up the functions to see the kind of things it can do, and the properties to see what information you can access about it.

Core Objects

Everything object Core is a CoreObject, and therefore has all the properties and functions in this section of the API documentation. They may also be more specific things, like Players, Abilities, or Cameras.

Each entry in the API Documentation has three sections: Event, Function, and Property. We will discuss events in the next lesson, so for now we will focus on these second two.

Properties

Properties are the attributes that you can access about an object using .propertyName.

The Return Type column will tell you the type of properties.

Enums

One of the property return types that you will see is an enum. This is a type of data that assigns a number to a meaning. Like a menu, “Press 1 for more information, press 2 to start an order …”

For example, Visibility has only 3 values: Inherit From Parent, Force On, and Force Off.

In code, what this means is:

print(Visibility.FORCE_OFF) -- will print "2"Code language: Lua (lua)

Read-Write, Read-Only

Not every property of an object is something that you should be able to change, but you may still need to look up what they are. These are Read-Only values.

A player’s ID, for example, is consistent for them across all Core games. No one game should be able to just change it. However, if you want to give a particular player special priviledges, you will need to be able to read that property.

Properties that you can change are Read-Write, meaning that you can both find out what they are, and change it.

Functions

Core API functions are behavior that Core Objects can either do, or can be done to them.

You can identify functions because they start with uppercase letter, and you call them using a :.

Example:

local positionVariable = myObjectName:GetPosition()Code language: Lua (lua)

You will almost always use : with the functions you find in the API.

You can call a CoreObject function with a ., but the first parameter on all these functions is the object itself. The : puts the object in as the first argument for you. If you get an error that says “Incorrect number or arguments”, it could just be that you used a . instead of a :.

Optional Arguments

You need to supply an input for every parameter listed in the function. The AttachToPlayer(Player, string socketName) for example, requires two inputs. A Player-type object and a string that matches one of the player sockets, like "right_ankle"

Events

Events are notifications that Core sends to your code when certain expected behaviors happen are your Core Objects. We will discuss them in more depth in the next chapter.