PuzzleScript Build System
Project description
PSBS
The PuzzleScript Build System!
PSBS combines multiple files into one puzzlescript source file and can export it to an HTML file or an online game hosted on a gist!
This is an early development release and changes may be made to the project structure and config file formats in the future.
Features
- Compile PuzzleScript games from many files using Jinja2 templates!
- Import images and spritesheets directly into your PuzzleScript game!
- Load existing PuzzleScript projects right from their gists!
- Load existing PuzzleScript projects from a source text file!
- Export PuzzleScript projects to html files!
- Export PuzzleScript projects to gists!
- Launch your project from play.html or the PuzzleScript editor!
- Supports most PuzzleScript forks!
- Use your favorite version control for your PuzzleScript projects!
- Tiled level editor integration!
Installing
If you already have Python 3.8 or greater and pip installed simply run the following command from your terminal
pip install psbs
If you don't have Python and pip installed: Download Python
Connecting to GitHub
PSBS will build your projects into PuzzleScript games without interacting with GitHub at all, however uploading and running your projects from gists requires an authorization token.
By default PSBS will attempt to run gh auth token
to recieve an authorization token from the GitHub command line tool. If you would like to use a different token or prefer not to install the GitHub command line tool you can run the following command.
psbs token
insert_your_token_here
Usage
Enter psbs
into your terminal to get a list of commands
Commands:
psbs new
Creates a new project
psbs build
Builds the project in the current working directory
psbs export
Builds project then export to game
psbs run
Builds project, exports it, then runs it in your web browser
psbs token
Check or set the GitHub auth token
For more information on these commands and to see available flags enter psbs help
command
CLI Example
psbs new myProject
cd myProject
psbs build
Getting To Know Your PSBS Project
Project Structure
├── config.yaml
├── bin
│ ├── script.txt (These files are generated by build command)
│ └── readme.txt
└── src
├── collisionlayers.pss (Default template files)
├── legend.pss (you can organize your project's templates however you like)
├── levels.pss
├── main.pss
├── objects.pss
├── prelude.pss
├── rules.pss
├── sounds.pss
└── wincondition.pss
Config.yaml
At the root of your project you will find a file called config.yaml containing configuration variables for your project
- gist_id: the id of the gist the export and run commands can use to store this project in
- engine: the url of the fork you are using, by default https://www.puzzlescript.net/
- template: the name of your root template file, by default main.pssengine: https://auroriax.github.io/PuzzleScript/
Below these are optional config variables for template extensions
- Images:
- alpha: whether to include the RGBA alpha values for transparency supported by some forks
- max_colors: maximum colors in output object, PuzzleScript can only handle 10 by default but some forks support up to 36 colors
Templates
PSBS uses Jinja2, a fast, expressive, extensible templating engine, to build your PuzzleScript project.
I'm currently working on official documentation but this is a work in progress.
To learn more about all of the features available to you check out the Jinja2 Template Designer Documentation.
To avoid conflicting with valid PuzzleScript code, the Jinja2 Tags have been changed as follows:
(% statements %) (( expressions )) (# comments #)
Images
A helper function has been added to the template environment Image(filename)
that will import an image file directly into your game as a PuzzleScript object!
Target
((image("images/target.png")))
Additionally, this helper function contains the following optional parameters (alpha=False, max_colors=10, left=0, top=0, width=None, height=None)
- left: (int) horizontal position in image to start importing from
- top: (int) vertical position in image to start importing from
- width: (int) width of the object to import, if None set to the width of the image file
- height: (int) height of the object to import, if None set to the height of the image file
By using the last four parameters listed one can load objects from a single image as a spritesheet.
(% set directions = ["down","left","up","right"] %) (# Can be placed in your main template #)
(% for dir in directions %)
Player_((dir))
((image("images/player.png",left=loop.index0*5,width=5,height=5)))
(% endfor %)
Tiled
tiled(filename)
Imports a Tiled map as a level! If you set generate_tileset to true in your config.yaml PSBS will attempt to generate a Tiled tileset from your game in the bin directory of your project. Tiled maps made with this tileset can be imported.
Tileset generation not compatible with Pattern:Script at this point in time.
message Welcome to the first level!
((tiled("src/levels/level1.tmx")))
message Here comes level 2!
((tiled("src/levels/level2.tmx")))
Releases
As of PSBS 0.2.0 a release name option has been added to config.yaml, this can be access within your template files using the following functions:
get_build: returns the release name
is_debug: returns true if the release name is "debug"
is_release: returns true if the release name is "release"
(% if is_debug %)
debug
verbose_logging
(% endif %)
markerobject
(% "transparent" if is_release else "red" %)
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.