Events

In real games, it is important to listen to changing conditions, such as a user clicking a button, or a score increasing. In programming, this is done using events. Powerlang allows you to connect to predefined events using the event directive.

The structure of an event directive is usually as follows:

event EventName("argument", output1, output2, ...) {

}

EventName represents the name of the event you want to connect to, and inside brackets we can pass arguments to the event and receive outputs related to it.

For example, we can listen to changes to Lighting like this:

event game.Lighting.AnyPropertyChanged(property, newValue) {
    print(property .. " got changed!")
}

So if anyone changes any Lighting property, for example the clock time or the brightness of the game, we will get an output about it.

It is also possible to pass arguments to events like this:

event game.Lighting.PropertyChanged("Brightness", newValue) {
    print("Now the brightness is " .. newValue)
}

Now this event will only trigger when the Brightness property is changed.

It may be tempting to pass the instance as an argument, especially when viewing at the Event Table at the end of this article, like so: event PropertyChanged(game.Lighting, "Brightness", newValue)

This is not currently supported, so please do not do it.

Service events

As you may have seen by the previous example, the example events "AnyPropertyChanged" and "PropertyChanged" have to be attached to an Instance, in our case game.Lighting. However there are some events that do not need to be attached. These are called service events. An example of a service event would be the player input events: LeftMouseDown, KeyDown, JumpRequest, etc.

Here's an example of printing "Hi!" when the user presses the E key on their keyboard:

event KeyDown("E") {
    print("Hi!")
}

All events (table)

For your convenience, here is a table with all events in Powerlang. Be sure to check this table each time you're unsure of an event name.

Use Ctrl+F to find the event you need. Remember that some of these only work on the server, and some of these only work on the client (but the majority should work in both places).

For service events, the first input is the instance that the event must be attached to.

Event Name	Description	Inputs	Outputs
ChildAdded	Triggered when a child is added to an object	Object	Child
ChildRemoved	Triggered when a child is removed from an object	Object	Child
DescendantAdded	Triggered when a descendant is added to an object	Object	Descendant
DescendantRemoved	Triggered when a descendant is removed from an object	Object	Descendant
PropertyChanged	Triggered when a property changes	Object, Property	NewValue
AnyPropertyChanged	Triggered when any property changes	Object	Property, NewValue
Heartbeat	Fires every frame	None	DeltaTime
BindToClose	Binds a function to be called when the game closes	None	None
OnClientEvent	Fired when a RemoteEvent is triggered to the client	RemoteEvent	Parameters
OnServerEvent	Fired when a RemoteEvent is triggered to the server	RemoteEvent	Player, Parameters
OnClientInvoke	Called when a RemoteFunction is invoked to the client	RemoteFunction	Parameters
OnServerInvoke	Called when a RemoteFunction is invoked to the server	RemoteFunction	Player, Parameters
Event	Fires when a BindableEvent is triggered	BindableEvent	Parameters
OnInvoke	Called when a BindableFunction is invoked	BindableFunction	Parameters
Touched	Triggered when a part is touched	Part	otherPart
TouchEnded	Triggered when a touch ends	Part	otherPart
ExplosionHit	Triggered when an explosion hits an object	Explosion	Part, Distance
ReachedTarget	Triggered when a BodyPosition reaches its target	BodyPosition	None
Equipped	Triggered when a tool is equipped	Tool	None
Unequipped	Triggered when a tool is unequipped	Tool	None
Activated	Triggered when a tool is activated	Tool	None
Deactivated	Triggered when a tool is deactivated	Tool	None
PlayerAdded	Fires when a player joins the game	None	Player
PlayerRemoving	Fires when a player is leaving the game	None	Player
Chatted	Triggered when a player sends a chat message	Player	Message
CharacterAdded	Fires when a player’s character is added	Player	Character
DialogChoiceSelected	Triggered when a dialog choice is selected	Dialog	Player, Choice
Died	Fires when a humanoid dies	Humanoid	None
FreeFalling	Fires when a humanoid starts/stops free-falling	Humanoid	Active
Jumping	Fires when a humanoid jumps	Humanoid	Active
Running	Fires when a humanoid starts running	Humanoid	Speed
Seated	Fires when a humanoid sits or stands up	Humanoid	Active, Seat
StateChanged	Fires when a humanoid's state changes	Humanoid	PreviousState, NewState
MoveToFinished	Triggered when a humanoid finishes moving	Humanoid	ReachedTarget
MouseClick	Triggered when a click detector is clicked	ClickDetector, InteractionType="Clicked"	Player
MouseHoverEnter	Triggered when the mouse hovers over an object	ClickDetector, InteractionType="Hover Enter"	Player
MouseHoverLeave	Triggered when the mouse leaves an object	ClickDetector, InteractionType="Hover Leave"	Player
RightMouseClick	Triggered on right-click	ClickDetector, InteractionType="Right Clicked"	Player
LeftMouseDownServer	Triggered on left mouse button down (server-side)	Player	None
LeftMouseUpServer	Triggered on left mouse button up (server-side)	Player	None
RightMouseDownServer	Triggered on right mouse button down (server-side)	Player	None
RightMouseUpServer	Triggered on right mouse button up (server-side)	Player	None
LeftMouseDown	Triggered on left mouse button down (local)	None	None
LeftMouseUp	Triggered on left mouse button up (local)	None	None
RightMouseDown	Triggered on right mouse button down (local)	None	None
RightMouseUp	Triggered on right mouse button up (local)	None	None
JumpRequest	Fires when a jump request is made	None	None
KeyDown	Fires when a key is pressed (local)	Key	None
KeyUp	Fires when a key is released (local)	Key	None
MouseEnter	Triggered when the mouse enters a GUI element	GUI	None
MouseLeave	Triggered when the mouse leaves a GUI element	GUI	None
MouseMoved	Fires when the mouse moves within a GUI	GUI	None
MouseWheelForward	Triggered when the mouse wheel scrolls forward	GUI	None
MouseWheelBackward	Triggered when the mouse wheel scrolls backward	GUI	None
LeftClick	Triggered on left click on a GUI button	GUIButton	None
LeftButtonDown	Triggered on left button down on a GUI button	GUIButton	None
LeftButtonUp	Triggered on left button up on a GUI button	GUIButton	None
RightClick	Triggered on right click on a GUI button	GUIButton	None
RightButtonDown	Triggered on right button down on a GUI button	GUIButton	None
RightButtonUp	Triggered on right button up on a GUI button	GUIButton	None
Focused	Fires when a TextBox is focused	TextBox	None
FocusLost	Fires when a TextBox loses focus	TextBox	None
RenderStepped	Fires every frame before rendering	None	deltaTime