Advanced

Documentation

Documentation
April 28, 2016 02:40PM
Script language
The script language used is based on LUA, running in a Sandbox. The LUA version currently used is version 5.1. You can read more about it in the LUA 5.1 manual.

LUA Sandbox
Our Sandbox environment is based on Mediawiki's LuaSandbox.

LUA Functions
Generally all functions that are harmless should be included. Functions that generally are excluded are those with file operations, network operations and similar. For more details, read Mediawiki's documentation for their LuaSandbox.

APIs from Project-GC
To get data from Project-GC there are a few API methods available. They are documented using doxygen here.
The functions have different names in LUA and in the documentation, since they are renamed for the Sandbox environment. For example, if you want to use the function
static PGC_LUA_Sandbox::CreateHTMLTable($data)
from LUA, it's called PGC.CreateHTMLTable($data).

Script keywords
The keywords are used to help others finding your script. This together with the script description is indexed for the search engine.

Script description
Try to describe what your script can do here, without being too long about it. If your script handles different parameters they should be documented here. In that way others might find the need for your source code for other challenges as well (see below about Tag config).

Tags
There are two terms to be aware of when creating scripts. Scripts and Tags. The scripts are the main part and include the source code itself. But without a tag it can not be executed. The tag contains information like gccode, configuration and a comment. The comment is mostly used to describe what the tag does, maybe the name of the challenge isn't clear enough. Note that even under development you then need to create a tag. You can leave both configuration and the gccode empty meanwhile.

Here is an example
  • You write a checker that checks if User X has Y finds in country Z.
  • You then create a tag that refers to the GC-code of a challenge that requires the user to have 1000 finds in Sweden. You then create a config that passes the parameter Y = 1000 and Z = Sweden as well (see below for more information about configs).
In this way, you can use the same script for many different challenges, since many of them are almost the same.

Tag config
When adding tags to your checker you can also add a json blob of config variables. Very useful if you want to use the same code but need different in-parameters. For example. 1000 finds in country X and 5000 finds in country Y. For that, add a json blob like this one:
{"count":"1000", "country":"Sweden"}
Your script will then receive this config as an array in its arguments, see Predefined arguments to the script.

You can check your json using an online Json Lint service like http://jsonlint.com/.

Predefined arguments to the script
All scripts will be provided by an array that looks like this:
array() {
  profileName => string
  profileId => string
  config => array
  gccode => string
  environmentSettings => array {
    cli => bool
    token => string (32 byte md5)
    maxMemoryUsage => int (bytes)
    maxExecutionTime => int (seconds)
    sandboxVersion => int (currently 2)
  }
}
... where the config array comes from the tag-config. You can retrieve the above by using code like this:
local args={...}
conf = args[1].config
profileName = args[1]['profileName']
profileId = args[1]['profileId']

Return values
A checker script should end with returning an array of values. The currently supported variables are: ok, log, html and map.
LUA syntax:
  • ok can be true or false, depending on if the given profile name fulfills the requirement or not.
  • log can be either false, or contain a string with a log example. Normally this is filled in if the given profile name fulfills the requirements, and the required log data is added here. The log will be prefixed with a hard coded string saying something like:
    XXX has used Project-GC to see if he/she qualifies for this challenge and he/she does.
  • html can be either false or contain a HTML blob that will be given back to the user. It could be more detailed feedback information for example. This blob will most likely not be useful to post in a log entry. This is an excellent output field to use when the user has not fulfilled the challenge and the script can give some helpful information.
return { ok = ok, log = log, html = false }

Enabling/Disabling scripts
While developing we recommend doing that on a script that is not enabled. In that way no-one else can find the script and try to execute code that might be faulty. In fact, the scripts are write protected when they are enabled.

If you need to update an existing script, we suggest that you copy the source code into a new script (fork it) while developing. The old script can then be kept available to everyone while you keep the new one disabled. When you are done you just copy the source back into the original, and optionally delete your temporary script.

If you need to add new tags to a script, you can keep the new tags disabled as well, until you have tested them.

Source code template
When creating a new script, you will get a start of ~50 lines of skeleton code. It's the basics to retrieve the arguments mentioned above, and a basic return structure.

Getting started
To get started, you are recommended to download the source from some of the current available checkers to see how they are built. An extremely simple example script would be http://project-gc.com/Challenges//19600.



Edited 4 time(s). Last edit at 02/20/2024 10:14AM by magma1447. (view changes)
Sorry, you can't reply to this topic. It has been closed.