<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:dc="http://purl.org/dc/elements/1.1/">
    <channel>
        <title>Project-GC Forum - Documentation</title>
        <description>Documentation and guidelines for writing challenge checkers and creating tags. Also some useful links.</description>
        <link>https://project-gc.com/forum/list?7</link>
        <lastBuildDate>Thu, 16 Apr 2026 03:50:17 +0000</lastBuildDate>
        <generator>Phorum 5.2.23</generator>
        <item>
            <guid>https://project-gc.com/forum/read?7,27,27#msg-27</guid>
            <title>List of types sizes, attribute (1 reply)</title>
            <link>https://project-gc.com/forum/read?7,27,27#msg-27</link>
            <description><![CDATA[ Correct name of types ans sizes are needed in checkers,<br />
This is a post to have the condensed and formatted to useful Json syntax to be easy used in checker tags<br />
<br />
List of sizes<br />
&quot;sizes&quot;:[<br />
&quot;Small&quot;,<br />
&quot;Not chosen&quot;,<br />
&quot;Regular&quot;,<br />
&quot;Other&quot;,<br />
&quot;Virtual&quot;,<br />
&quot;Micro&quot;,<br />
&quot;Large&quot;<br />
]<br />
<br />
&quot;types&quot;:[<br />
&quot;Traditional Cache&quot;,<br />
&quot;Unknown Cache&quot;,<br />
&quot;Multi-cache&quot;,<br />
&quot;Event Cache&quot;,<br />
&quot;Earthcache&quot;,<br />
&quot;Letterbox Hybrid&quot;,<br />
&quot;Cache In Trash Out Event&quot;,<br />
&quot;Virtual Cache&quot;,<br />
&quot;Wherigo Cache&quot;,<br />
&quot;Webcam Cache&quot;,<br />
&quot;Lost and Found Event Cache&quot;,<br />
&quot;Locationless (Reverse) Cache&quot;,<br />
&quot;Mega-Event Cache&quot;,<br />
&quot;GPS Adventures Exhibit&quot;,<br />
&quot;Project APE Cache&quot;,<br />
&quot;Groundspeak Block Party&quot;,<br />
&quot;Giga-Event Cache&quot;,<br />
&quot;Groundspeak HQ&quot;,<br />
&quot;Groundspeak Lost and Found Celebration&quot;<br />
]<br />
<br />
List of attributes<br />
<pre class="bbcode">
&gt; select * from attributes;
+----+----------+---------------------------------+---------------+-------------------+
| id | group_id | attribute_name                  | has_no_option | base_filename     |
+----+----------+---------------------------------+---------------+-------------------+
|  1 |        1 | Dogs                            |             1 | dogs              |
|  2 |        2 | Access/parking fee              |             0 | fee               |
|  3 |        2 | Climbing gear required          |             0 | rappelling        |
|  4 |        2 | Boat required                   |             0 | boat              |
|  5 |        2 | Scuba gear required             |             0 | scuba             |
|  6 |        3 | Recommended for kids            |             1 | kids              |
|  7 |        3 | Takes less than one hour        |             1 | onehour           |
|  8 |        3 | Scenic view                     |             1 | scenic            |
|  9 |        3 | Significant hike                |             1 | hiking            |
| 10 |        3 | Difficult climb                 |             1 | climbing          |
| 11 |        3 | May require wading              |             0 | wading            |
| 12 |        3 | May require swimming            |             0 | swimming          |
| 13 |        3 | Available 24/7                  |             1 | available         |
| 14 |        3 | Recommended at night            |             1 | night             |
| 15 |        3 | Available in winter             |             1 | winter            |
| 17 |        4 | Poisonous plants                |             1 | poisonoak         |
| 18 |        4 | Dangerous animals               |             0 | dangerousanimals  |
| 19 |        4 | Ticks                           |             0 | ticks             |
| 20 |        4 | Abandoned mine                  |             0 | mine              |
| 21 |        4 | Cliff/falling rocks             |             0 | cliff             |
| 22 |        4 | Hunting area                    |             0 | hunting           |
| 23 |        4 | Dangerous area                  |             0 | danger            |
| 24 |        5 | Wheelchair accessible           |             1 | wheelchair        |
| 25 |        5 | Parking nearby                  |             1 | parking           |
| 26 |        5 | Public transportation nearby    |             0 | public            |
| 27 |        5 | Drinking water nearby           |             1 | water             |
| 28 |        5 | Public restrooms nearby         |             1 | restrooms         |
| 29 |        5 | Telephone nearby                |             1 | phone             |
| 30 |        5 | Picnic tables nearby            |             1 | picnic            |
| 31 |        5 | Camping nearby                  |             1 | camping           |
| 32 |        1 | Bicycles                        |             1 | bicycles          |
| 33 |        1 | Motorcycles                     |             1 | motorcycles       |
| 34 |        1 | Quads                           |             1 | quads             |
| 35 |        1 | Off-road vehicles               |             1 | jeeps             |
| 36 |        1 | Snowmobiles                     |             1 | snowmobiles       |
| 37 |        1 | Horses                          |             1 | horses            |
| 38 |        1 | Campfires                       |             1 | campfires         |
| 39 |        4 | Thorns                          |             0 | thorn             |
| 40 |        3 | Stealth required                |             1 | stealth           |
| 41 |        5 | Stroller accessible             |             1 | stroller          |
| 42 |        3 | Needs maintenance               |             0 | firstaid          |
| 43 |        3 | Livestock nearby                |             0 | cow               |
| 44 |        2 | Flashlight required             |             0 | flashlight        |
| 45 |        6 | Lost and Found tour             |             0 | landf             |
| 46 |        1 | Trucks/RVs                      |             1 | rv                |
| 47 |        3 | Field puzzle                    |             1 | field_puzzle      |
| 48 |        2 | UV light required               |             0 | UV                |
| 49 |        2 | May require snowshoes           |             0 | snowshoes         |
| 50 |        2 | May require cross country skis  |             0 | skiis             |
| 51 |        2 | Special tool required           |             0 | s-tool            |
| 52 |        3 | Night cache                     |             1 | nightcache        |
| 53 |        3 | Park and grab                   |             1 | parkngrab         |
| 54 |        3 | Abandoned structure             |             1 | AbandonedBuilding |
| 55 |        3 | Short hike (&lt;1 km)              |             1 | hike_short        |
| 56 |        3 | Medium hike (1 km-10 km)        |             1 | hike_med          |
| 57 |        3 | Long hike (&gt;10 km)              |             1 | hike_long         |
| 58 |        5 | Fuel nearby                     |             1 | fuel              |
| 59 |        5 | Food nearby                     |             1 | food              |
| 60 |        2 | Wireless beacon                 |             0 | wirelessbeacon    |
| 61 |        6 | Partnership cache               |             0 | partnership       |
| 62 |        3 | Seasonal access                 |             1 | seasonal          |
| 63 |        3 | Recommended for tourists        |             1 | touristOK         |
| 64 |        2 | Tree climbing required          |             1 | treeclimbing      |
| 65 |        3 | Yard (private residence)        |             1 | frontyard         |
| 66 |        3 | Teamwork cache                  |             1 | teamwork          |
| 67 |        6 | GeoTour                         |             0 | geotour           |
| 69 |        3 | Bonus cache                     |             0 | bonuscache        |
| 70 |        3 | Power trail                     |             0 | powertrail        |
| 71 |        3 | Challenge cache                 |             0 | challengecache    |
| 72 |        6 | Geocaching.com solution checker |             0 | hqsolutionchecker |
+----+----------+---------------------------------+---------------+-------------------+
70 rows in set (0.001 sec)
</pre>]]></description>
            <dc:creator>Target.</dc:creator>
            <category>Documentation</category>
            <pubDate>Wed, 04 May 2016 19:03:11 +0000</pubDate>
        </item>
        <item>
            <guid>https://project-gc.com/forum/read?7,17,17#msg-17</guid>
            <title>Developers FAQ (no replies)</title>
            <link>https://project-gc.com/forum/read?7,17,17#msg-17</link>
            <description><![CDATA[ <b>Why was LUA chosen?</b><br />
LUA is an excellent language for Sandboxing.<br />
<br />
<b>What is a Sandbox?</b><br />
We will refer to <a href="http://en.wikipedia.org/wiki/Sandbox_(computer_security)"  rel="nofollow">Wikipedia</a> for that.<br />
<br />
<b>My script ends up with an empty page</b><br />
There generally are two reasons for this.<br />
<ul><li> The scripts are limited to the use of about 1024 MB of memory, running on a dedicated server. </li><li> <s>The maximum execution time is 30 seconds.</s> A timeout should now return such error message. </li></ul>]]></description>
            <dc:creator>magma1447</dc:creator>
            <category>Documentation</category>
            <pubDate>Thu, 28 Apr 2016 12:44:24 +0000</pubDate>
        </item>
        <item>
            <guid>https://project-gc.com/forum/read?7,16,16#msg-16</guid>
            <title>Documentation (no replies)</title>
            <link>https://project-gc.com/forum/read?7,16,16#msg-16</link>
            <description><![CDATA[ <span style="font-size:large">Script language</span><br />
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 <a href="http://www.lua.org/manual/5.1/"  rel="nofollow">LUA 5.1 manual</a>.<br />
<br />
<span style="font-size:large">LUA Sandbox</span><br />
Our Sandbox environment is based on <a href="https://www.mediawiki.org/wiki/LuaSandbox"  rel="nofollow">Mediawiki&#039;s LuaSandbox</a>.<br />
<br />
<span style="font-size:large">LUA Functions</span><br />
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&#039;s documentation for their LuaSandbox.<br />
<br />
<span style="font-size:large">APIs from Project-GC</span><br />
To get data from Project-GC there are a few API methods available. They are documented using doxygen <a href="http://project-gc.com/doxygen/lua-sandbox/classPGC__LUA__Sandbox.html"  rel="nofollow">here</a>.<br />
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<br />
<pre class="bbcode">static PGC_LUA_Sandbox::CreateHTMLTable($data)</pre> from LUA, it&#039;s called PGC.CreateHTMLTable($data).<br />
<br />
<span style="font-size:large">Script keywords</span><br />
The keywords are used to help others finding your script. This together with the script description is indexed for the search engine.<br />
<br />
<span style="font-size:large">Script description</span><br />
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).<br />
<br />
<span style="font-size:large">Tags</span><br />
There are two terms to be aware of when creating scripts. <i>Scripts</i> and <i>Tags</i>. The scripts are the main part and include the source code itself. But without a <i>tag</i> 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&#039;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.<br />
<br />
Here is an example<br />
<ul><li> You write a checker that checks if User X has Y finds in country Z. </li><li> 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). </li></ul>
In this way, you can use the same script for many different challenges, since many of them are almost the same.<br />
<br />
<span style="font-size:large">Tag config</span><br />
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:<br />
<pre class="bbcode">{&quot;count&quot;:&quot;1000&quot;, &quot;country&quot;:&quot;Sweden&quot;}</pre>
Your script will then receive this config as an array in its arguments, see <i>Predefined arguments to the script</i>.<br />
<br />
You can check your json using an online Json Lint service like <a href="http://jsonlint.com/"  rel="nofollow">http://jsonlint.com/</a>.<br />
<br />
<span style="font-size:large">Predefined arguments to the script</span><br />
All scripts will be provided by an array that looks like this:<br />
<pre class="bbcode">array() {
  profileName =&gt; string
  profileId =&gt; string
  config =&gt; array
  gccode =&gt; string
  environmentSettings =&gt; array {
    cli =&gt; bool
    token =&gt; string (32 byte md5)
    maxMemoryUsage =&gt; int (bytes)
    maxExecutionTime =&gt; int (seconds)
    sandboxVersion =&gt; int (currently 2)
  }
}</pre>
... where the config array comes from the tag-config. You can retrieve the above by using code like this:<br />
<pre class="bbcode">local args={...}
conf = args[1].config
profileName = args[1][&#039;profileName&#039;]
profileId = args[1][&#039;profileId&#039;]</pre>
<br />
<span style="font-size:large">Return values</span><br />
A checker script should end with returning an array of values. The currently supported variables are: ok, log, html and map.<br />
LUA syntax:<br />
<ul><li> <b>ok</b> can be true or false, depending on if the given profile name fulfills the requirement or not. </li><li> <b>log</b> 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: <br /> <i>XXX has used Project-GC to see if he/she qualifies for this challenge and he/she does.</i> </li><li> <b>html</b> 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. </li></ul>
<pre class="bbcode">return { ok = ok, log = log, html = false }</pre>
<br />
<span style="font-size:large">Enabling/Disabling scripts</span><br />
While developing we recommend doing that on a script that is <b>not</b> 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.<br />
<br />
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.<br />
<br />
If you need to add new tags to a script, you can keep the new tags disabled as well, until you have tested them.<br />
<br />
<span style="font-size:large">Source code template</span><br />
When creating a new script, you will get a start of ~50 lines of skeleton code. It&#039;s the basics to retrieve the arguments mentioned above, and a basic return structure.<br />
<br />
<span style="font-size:large">Getting started</span><br />
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 <a href="http://project-gc.com/Challenges//19600"  rel="nofollow">http://project-gc.com/Challenges//19600</a>.]]></description>
            <dc:creator>magma1447</dc:creator>
            <category>Documentation</category>
            <pubDate>Thu, 28 Apr 2016 12:40:56 +0000</pubDate>
        </item>
        <item>
            <guid>https://project-gc.com/forum/read?7,15,15#msg-15</guid>
            <title>Guidelines (no replies)</title>
            <link>https://project-gc.com/forum/read?7,15,15#msg-15</link>
            <description><![CDATA[ This is a work in progress. We will try to update this now when the moratorium will be removed.<br />
<br />
<ul><li> Scripts that uses parameters should document them in the script description. This will make it easier for others to use your script. </li><li> Use keywords to make it easier to find the script. They can be in any language, or in several languages. </li><li> Don&#039;t fetch more data than needed when using GetFinds(). There is a filter, which also with the correct usage can be combined with the config-input. Saves you development time, and saves the servers from memory usage. </li><li> If you implement a checker for a challenge that isn&#039;t 100% accurate, which may be for technical reasons, make it very clear in the output. Preferably both in the example log and the html output. </li><li> Use the log output variable for example logs, preferably using Markdown. Monospace lists should use the Markdown indentation of four spaces (with a line of four spaces only before the list as well). </li><li> Script outputs should be in English. You can add an additional language as well, but English is required. </li><li> Use the html output variable for more detailed output. You can actually output pure text here as well, but the line-breaks need to be &lt;br&gt;. </li><li> Don&#039;t concat strings inside loops. Add them to tables and then join the table instead. This is enormously faster and less memory consuming. This is very important </li><li> After you have created a tag. Use the verify button to run the tag for the last ten who logged the challenge. Normally they should all be OK. </li><li> After you have created a tag, test it on someone with plenty of finds (&gt;10000) and someone with 0 finds. </li><li> Don&#039;t create identical tags using the same script. There is a housekeeping job that will automatically remove duplicates, but keep the original. Creating another tag for the same challenge can be ok though. If it is more correct, or uses a script that gives better output. </li><li> In the tag config use int for integers and strings for strings. Ie, { &quot;required&quot;: 100 } is more correct than { &quot;required&quot;: &quot;100&quot; }. </li><li> Note that neither region or county names always are unique. For example county Waterloo exists in both Canada and Belgium. The region Central exists in four different countries. Make sure you handle this in your scripts and configurations when needed. <b>Using a region/county filter without providing the country will result in errors in the future.</b> </li></ul>]]></description>
            <dc:creator>magma1447</dc:creator>
            <category>Documentation</category>
            <pubDate>Thu, 28 Apr 2016 12:34:22 +0000</pubDate>
        </item>
        <item>
            <guid>https://project-gc.com/forum/read?7,14,14#msg-14</guid>
            <title>Planned API methods (no replies)</title>
            <link>https://project-gc.com/forum/read?7,14,14#msg-14</link>
            <description><![CDATA[ <b>Retrieve last log before the users log</b><br />
Purpose: For lonely caches.<br />
The details are yet to be determined. Either we just retrieve the log before, which is what most challenges today is about. But what if what a group found it two years after the former finder. Then only one gets the lonely accomplishment.<br />
The alternative is to retrieve all finds from the same date as the finder, and all finds from the date (found) before that. Then the script can handle it from there. We are not yet aware of the performance issues about this though.<br />
We will look into this task in the beginning of June and expect some form of result from it, but we need to make performance measures before we know what we can deliver.<br />
<br />
<b>Home coordinates</b><br />
We could probably expose home coordinates in the case where someone runs a checker on him/her-self. It will however then be impossible for the cache owner to verify the result.<br />
<br />
<b>Home country/region</b><br />
Get statistical home country for user, and in those cases we have calculated it, the region as well. This is in most cases correct, but not always. It&#039;s the data used all over Project-GC to determine in what country a geocacher lives in.]]></description>
            <dc:creator>magma1447</dc:creator>
            <category>Documentation</category>
            <pubDate>Thu, 28 Apr 2016 12:25:16 +0000</pubDate>
        </item>
    </channel>
</rss>
