This page describes the basics of setting up a Polycode application using C++ or Lua.

Contents

Polycode applications in C++.

A Polycode application is centered around the Core class, which is initialized with a PolycodeView instance.

The Core is an abstract class that defines platform-related functionality, such as updates, window management, disk operations, thread managment and input and is implemented as a subclass on each supported platform. To initialize a Polycode application, you must instantiate a Core instance, passing it some intial parameters and a pointer to a PolycodeView instance.

PolycodeView is a class that contains platform-specific windowing information. It is imlemented completely differently on each platform to fit that platform's programming paradigm. For example, on the Mac, PolycodeView is an Objective-C class that sublcasses the Cocoa NSOpenGLView while on Windows it is a C++ class that contains the window handle. This system allows you to instantiate Polycode into a larger application and provides flexibility around the main loop and windowing of the application, with the tradeoff that the setup and basic loop differ a bit on each platform.

See the template project in each platform's distribution for details on platform-specific setup and loop implementations. You can also copy the Template project to use as a base for your C++ project.

The platform-specific Core subclass is defined on each platform as POLYCODE_CORE. In this example, we initialize the Core as a 1280x720 window with vSync, running at 90 frames per second.

C++
Core *core = new POLYCODE_CORE(view, 1280,720,false,true,0,0,90, 0, true);

Application loop in C++.

After the Core is instantiated, it must be updated in a loop. On most platforms, a simple while loop will suffice, though on some platforms, like Mac, the loop is done via a Cocoa timer. See the template project for each platform for loop impementation details.

The easiest way to update the Core is to call updateAndRender on it. This will update all of Polycode's internal systems and then render active scenes to the screen. This method will return Polycode's internal running state and you can use it as a base for your main loop.

C++
bool done = false;
while(!done) {
	Number elapsed = core->getElapsed();
	done = core->updateAndRender();
}

updateAndRender is basically a convenience wrapper that calls Update() and Render() in one method, but in some cases, you would want to separate your Update and Render calls and run some code after the update has happened, but before things are rendered.

C++
bool done = false;
while(!done) {
	done = core->Update();
	Number elapsed = core->getElapsed();
	core->Render();
}

Update is in turn a convenience wrapper for Polycode's internal fixed update system. If your application uses a physics module or does any kind of granular collision detection, it is advised that you use a fixed update loop in your application alongside Polycode's fixed update. To do that, you need to first call systemUpdate() on the core, and then keep calling fixedUpdate until it returns false, executing your code in between. Polycode ensures that this will only happen at a fixed interval defined by the framerate the Core was set to. This loop also allows you to respond to physics events that happen internally in Polycode during the fixed updates.

C++
bool done = false;
while(!done) {
	done = core->systemUpdate();
	while(core->fixedUpdate()) {
		// this code will be called at a fixed interval 
	}
	core->Render();
}

Polycode Lua applications using the IDE.

To create new Lua application in the IDE, select File→New Project from the application menu and choose a template to start with.

You don't have to write any code to initialize a Lua application, it will run even with a blank source file and updated and rendered automatically. To run the application, click on the big play button or choose Project→Run Project from the application menu.

You can change the application's default settings by clicking on the polyproject file in the project tree. This will allow you to change the resolution, texture filtering options, link dynamic modules, add fonts to your application and set the main lua source file for your app. By default, the main source file of a new application is Main.lua

Polycode Lua applications using commmand line tools.

If you prefer not to use the Polycode IDE, you can manually call the standalone command line tools that the IDE uses under the hood and have your own toolchain.

To do this, you will need to manually create the polyproject file that the IDE generates. A polyproject is an XML file that defines the basic application settings and the files that are bundled into the polyapp.

XML
<?xml version="1.0" ?>
<PolycodeProject defaultWidth="640" defaultHeight="480" antiAliasingLevel="0" entryPoint="Scripts/Main.lua" textureFiltering="linear" vSync="false" anisotropyLevel="0" frameRate="60">
    <backgroundColor red="0.25" green="0.25" blue="0.25" />
    <packedItems>
        <item type="folder" path="Scripts" />
    </packedItems>
</PolycodeProject>

To build a Polycode Lua project using the command line tools, you need to add the standalone tool directory (Standalone/Bin in the Polycode IDE folder, or in Contents/Resources of Polycode.app on Mac) to your path and call the polybuild tool.

polybuild --config=DemoProject.polyproject --out=DemoApp.polyapp

This will build the polyapp file that you can then run with the PolycodePlayer. To create a standalone application for a supported platform, simply replace main.polyapp in any of the standalone player builds under Standalone/Publish with your application's polyapp file.

Application loop in Lua.

The update and rendering loop in Lua is managed internally by the Polycode Player, so you do not need to call Update or Render yourself. The player will call a global Lua function called Update on every update frame and pass it the time elapsed since last frame. You can implement this function yourself and do all of your application's updates in that function.

Lua
function Update(elapsed)
	-- update code here
end

If you wish to use a fixed update loop in Lua, you can implement a global fixedUpdate function, which will be called on every fixed update.

Lua
function fixedUpdate()
	-- fixed update code here
end