PuzzleScript Support Questions

[increpare]

Hello,

I made PuzzleScript ( Github repo ), a puzzle-game-making scripting language that exists mostly in the browser, but when games are distributed they are done as .txt files. I've been wondering about getting Puzzlescript in Linguist for a while, but there are two issues: the provenance of the evidence, and our use of the .txt extension.

I've assembled a corpus of PuzzleScript games on GitHub (42,810 gists from 3,006 accounts, versus 32 GitHub repositories containing 1,765 puzzlescript files. This gives us 44,576 files in total, of which 37,256 are unique):

Examples from the corpus:

• Heroes of Sokoban - playable link
• Vines - playable link

I've prepared a content heuristic and TextMate grammar.

• The heuristic fingers 36,764/37,256 files as being PuzzleScript games (98.68%).
• No false-positives amongst the 3,407 existing Linguist text-based samples.
• The TextMate tokenizer got through all 37,256 files without errors or timeouts.

Because PuzzleScript games are usually shared as gists, repository code doesn't capture a fraction of the ecosystem on github (42.8k vs 1.8k files). The documented usage requirement is based on indexed public repository files, excluding forks, with a reasonable distribution of owners and repositories.

The requirement:

At least 2,000 files per extension, indexed by GitHub Search in the last year, excluding forks.

For context, the archive includes the following recognized PuzzleScript .txt files in public, non-fork Gists, grouped by Gist creation date. These are creation dates, rather than GitHub Search indexing dates, so I’m not claiming they directly satisfy the requirement. The archive runs through early April 2026.

Gist creation period	Files	Named owners	Distinct contents
Since 13 October 2025	2,729	279	2,299
Calendar year 2025	4,537	510	3,806

So,

1 Would a submitted list of links to public gists be ok as usage evidence for PuzzleScript?

2. Is the proposed conservative .txt approach ok in principle, given the existing content-based treatment of other .txt formats?

Thank you for your time :)
Stephen Lavelle / increpare

[Alhadis]

While I'm disappointed by the lack of Lemmings and Commander Keen representation, I have to admit, this is a very intriguing language, both in its scope and its design.

Regarding usage among Gists, however… I'm actually unsure, as we've never had to judge a language's real-world usage by anything other than repositories. I'll need the beseech the wisdom of GitHub staff:

*summons @lildude to the conversation*

[lildude]

Interesting… I agree with @Alhadis, I don't think we've had this come up before.

Would a submitted list of links to public gists be ok as usage evidence for PuzzleScript?

No. We really need reproducible evidence, hence requiring a search query. If you can provide a Gist search query that supports the usage to accompany the repo support, I think that'll be a good start. Remember, you can use regex in search so you should be able to use your planned heuristic to improve the quality of the results.

Is the proposed conservative .txt approach ok in principle, given the existing content-based treatment of other .txt formats?

Yes if there's sufficient evidence, but you will need your heuristic to be 100% accurate at never matching anything other than this language, like the others for this extension. It's better to under match your language than over match.

[increpare]

Hey, thanks for your swift and very attentive replies. It's very motivating - I learned a whole lot about TextMate grammars this week lol.

We really need reproducible evidence, hence requiring a search query. If you can provide a Gist search query that supports the usage to accompany the repo support, I think that'll be a good start.

Here are some queries

Search	Gist results
objects legend collisionlayers rules extension:txt fork:false	36,884
The same search excluding my account	35,358
Created since 23 October 2025, excluding my account	5,082
That recent search also excluding NoamNF	4,732

(The final row is excluding results from a recent prolific contributor).

Many of the searches, because of how gist works I guess, display readme.txt files in the results card (puzzlescript by default submits a readme file to gist along with the source code script when you share), but the puzzlescript file should be there if you click through.

( For comparison again, the repository search link returns 2.2k results )

Yes if there's sufficient evidence, but you will need your heuristic to be 100% accurate at never matching anything other than this language, like the others for this extension. It's better to under match your language than over match.

For the heuristic I picked the following constraints (things that experimentally occur in the 50kb window that Linguist looks at):

    - pattern: '(?i)^[ \t]*collisionlayers[ \t]*(\(|\r?$)'
    - pattern: '\[[^\r\n]*\][ \t]*->'

(This asks for one of the mandated section headers, as well as something that looks like a puzzlescript replacement rule i.e. it would match "[ no cat ] -> [ cat ]")

With the above heuristic Oniguruma doesn't flag any of the current 3,404 upstream Linguist sample files as being puzzlescript (including the 24 .txt samples).

Out of an abundance of caution, I looked for (non-puzzlescript) files on github that mention "collisionlayers". Only one of the 81 results I looked at matched the first required required pattern ((?i)^[ \t]*collisionlayers[ \t]*(\(|\r?$)), but that was beyond Linguist's 50kb window.

Type	Link	Occurrence
Development Notes	specfreqpublic	CollisionLayers, must scan for 1,5
Development Notes	GameEngine	collisionStatic and collisionLayers
Development Notes	VEX	agentcollisionlayers (deprecates agentcollisionlayer)
Build Files	Carrot	${EngineRoot}physics/CollisionLayers.cpp
Build Files	ECX_Engine	EC_CollisionLayers.h
Build Files	DroidNet	"CollisionLayers.h"
Exported Strings/Symbols	CS2	m_bClothCollisionLayers
Exported Strings/Symbols	Dota2	m_bClothCollisionLayers

( all ~80 of them are here )

====

So, I hope that's the right amount of information for you to know if it's a good idea to have PuzzleScript in Linguist or not - let me know if there are any other things you need to know. I have a TextMate grammar/etc ready to go :)

Thanks for your time :)

Stephen