EventBlock

Ashley's avatar
Medal
Construct Team Founder
Published 2 Jul, 2018
414 words
~2-3 mins

The EventBlock class represents an event block in an event sheet. This is also used as the "current event" in the EventStack.

EventBlocks consist of conditions and actions and are either AND blocks (the default), running when all conditions are met, or OR blocks, running when any condition is met.

Construct tracks the "SOL modifiers" for each EventBlock. These are the ObjectClasses that the event may pick from, i.e. the SOLs that may be modified by running the event. This is an important consideration when working with events. Alterations to SOLs that are not in the SOL modifiers list are not permitted.

Retriggering events

The Retrigger() method is useful for implementing looping conditions. It should be used as such:

  1. Get the current event stack frame
  2. Push a new event stack frame
  3. In a loop:
    1. Push a copy of the SOL
    2. Retrigger the current event, passing both the old and new stack frames
    3. Pop the SOL
  4. Pop the event stack frame
  5. Return false from the condition method. (The event has already been executed the required number of times, and if it returns true, Construct will continue to run the event as normal, which is usually unnecessary.)

The following code example demonstrates the necessary calls.

MyLoopingCondition()
{
	// Get necessary references
	const runtime = this._runtime;
	const eventSheetManager = runtime.GetEventSheetManager();
	const currentEvent = runtime.GetCurrentEvent();
	const solModifiers = currentEvent.GetSolModifiers();
	const eventStack = runtime.GetEventStack();

	// Get current stack frame and push new one
	const oldFrame = eventStack.GetCurrentStackFrame();
	const newFrame = eventStack.Push(currentEvent);

	for (const item of myArray)
	{
		// ... optionally update state here ...

		// Push a copy of the current SOL
		eventSheetManager.PushCopySol(solModifiers);

		// Retrigger the current event, running a single loop iteration
		currentEvent.Retrigger(oldFrame, newFrame);

		// Pop the current SOL
		eventSheetManager.PopSol(solModifiers);
	}
	
	// Pop the event stack frame
	eventStack.Pop();

	// Return false since event already executed
	return false;
}

Methods

GetEventSheetManager()

Return the associated EventSheetManager.

GetRuntime()

Return the associated Runtime.

GetParent()

Return the parent EventBlock, or null if this is a top-level event.

IsOrBlock()

If true, this is an OR block, else it is an AND block.

GetSolModifiers()

Return an array of ObjectClass that the event block may modify.

Retrigger(oldFrame, newFrame)

Re-run the current event. This is useful for implementing looping conditions. Prior to calling this, you must push a new EventStackFrame, and pass both the old and the new stack frames to this call. Be sure to pop the pushed stack frame once complete. See the code sample above.