Cute Exporter»Blog

Upcoming Lua Scripting Support.

Cute Exporter has been exporting the metadata about the texture atlas as a json file. This was because it's easy to do, and I know json better than other file formats.
But, there are game engines that don't use json. I want Cute Exporter to support those use cases.

My goals in supporting this use case are:

  • Easy setup.
  • Let user do what they want.
  • User provided file extension.
  • Easy to change.

Using a template file.

One solution may be to have a template format. You would create a template and direct Cute Exporter to fill it in. This works fine, it's a perfectly valid solution. For basic use cases this is all you need. However, if you are wanting to do anything more advanced, either you can't, or you have to write an extension to the template engine in another programing language. For Example, Handlebars allows you to add in custom filters and functions to your template written in javascript.

This is easy to set up for the user and easy to change. It fails in user provided file extension. Let user do what they want is a 50/50 here. They can do what they want, as long as it's not advanced.

Now we could extend our scheme to have a definition file written in json or XML. The definition would provide the path to the template file and the file extension. Not bad, but now the user has 3 different files and file formats.

Additionally, there is the issue of where do these file get saved? The files could be saved to a known location on disk. Doing this makes it easy for the program to find and list all different export formats they support along with user provided ones.

I want any user provided data to be located nearby the project file. I want the user to be able to version control their code, images, and exporter tools in the same place. If I want multiple people to work on the project with me, I have to pass along the custom export format in addition to the code and instruct them how to install it.

Lua scripting

The way I decided to solve this was to give the user a programming language, Lua. The user can use any template format or techniques they want. All Cute Exporter cares about is returning a string that it will save to a file.

How it works

In the settings the user will tell Cute Exporter it wants to use a custom exporter and provides a path to the script to run. Cute Exporter saves the path to this file relative to the directory the project file is saved in. With the intention that the user will save the exporter script with the rest of their code and assets. That way if you want other people to work with you, they don't need to worry about any setup with Cute Exporter. Download Cute Exporter and open the project file.

When it comes time to export the data, Cute Exporter will run the custom script. To standardize things it runs a function in the script named `doExport` passing in the metadata for the export. It expects a string to be returned. The string returned will be saved to the data file.

What about file extension? The great thing about Lua is it's easy to use for configuration in addition to scripting. In keeping with making it simple the user can optionally provide a global variable declaring the file extension. Cute Exporter will run the script and read the global variable `outputFileExt` if it exists. The string value in that variable is used as the file extension for the custom export format.

I think this hits all my goals. It's easy to setup with a few clicks in the settings. Lua is a full fledged programming language, the user should have no trouble doing what they want. The user can provide a file extension. And the script is easy to change. On top of that, we expect one file only for the user to provide config info about their format. Lua can include other Lua files and code and this implementation allows that, giving the custom format access to any code written by others with a simple import statement.

Small example.

Let's wrap this up. Here's a minimum example of an export format.

outputFileExt = "custom"
function doExport(data) 
	return "hello!"

The resulting data file will have the extension `.custom` and the text `hello!` in it. A non trivial format should do something with the data provided but as shown, Cute Exporter only cares about the return value.
Edited by Dawoodoz on
I use the ini format (one assignment per row between key and value) for sprite maps in C++, because it only takes around 20 lines of code to parse and you can have planar comma separated integer lists as strings for multiple elements. Having scripts would only make it harder to process it as transparent data in other applications. The more limited the format is, the more you know what you can do without having to assume that random features are not used.
Simon Anciaux, Edited by Simon Anciaux on
I think the point of the script is for cute exporter to generate data in any format the user wants. So you'd provide a lua script to generated the ini file if that's what you want.

One thing you could do maybe is to pass the path to the export folder, and the file name without extension and let the script write the file to disk so you don't have to worry about the extension ? Also maybe you could write the data as a binary file to disk and call any user specify program with the file as argument (and the path and file name without extension) so that if the use prefer another language they can do it ?
Clay Murray, Edited by Clay Murray on Reason: more info
Wow I never got a notification for this thanks for your comment. Yeah the point of this feature is you should be able to output your file in whatever format you want with the scripting support. So if you want to output as an ini it should be super simple to do so. Also if you can give me a minimal example of what you would want an ini file to look like I might be able to cook up a built in exporter to make it easy.
Clay Murray,
You are correct. Also I really like your suggestion of a binary file and calling a user specified program. My only issue with that being I like this file to be able to be shared across devices so I want to make sure that the path specified is common for anyone who uses it. But it's a really good idea.
Simon Anciaux,
I want to make sure that the path specified is common for anyone who uses it

I think that's a user problem to figure out, not for your tool to guarantee (as it really can't). The user can add their program in the path, use subst drive, have a defined file hierarchy... it's really something a team figures out, and anything your tool might do could work against the user choice or just add an unnecessary constraint.
Clay Murray,
Sorry I see what you mean, I am misspeaking. I want paths to be relative to the project file so there is less that needs to be set up. If the external program is on the path then that's an easy solution or maybe just a local config for certain things that isn't shared with the team. Can have a simple ini