Decker

Decker is a multimedia platform for creating and sharing interactive documents, with sound, images, hypertext, and scripted behavior.

You can learn more about Decker on my website, on the community forum, or you can just dive in and try it online. Periodic binary releases of Decker for MacOS and Windows are available on Itch.io.

If you're interested in Lil, Decker's scripting language, you can access documentation and play with it in your browser at trylil.

Web-Decker

Decker is available as a web application (written in vanilla JavaScript) which is distributed as a single freestanding HTML file. Web-Decker can be built with a make script. The test suite uses Node.js:

make testjs
make web-decker
make runweb      # (optional) open in your default browser

Web service

Web-decker allows your web browser to point to a local file and run Decker in js. If you would like to serve Decker, you will need a web service.

You can serve Decker as a web-app by using a node.js server. You will need node and npx installed. You will need to install the dependencies and then start the server.

npm i
npm start

This will start it by default on the 3000 port. You can change this port in the server.py file (line 5, change the number 3000 to whichever port number you would like.)

Docker

This file contains instructions for building and running the Decker application in a Docker container.

Prerequisites

• Docker must be installed on your system.

Building the Docker Image

To build the Docker image, open a terminal in the root of the project and run the following command. This will build the Docker image and tag it with the name decker:

docker build -t decker .

Running the Docker Container

Once the image is built, you can run it as a container with the following command. This will start the container and map port 3000 on your host machine to port 3000 in the container:

docker run -p 3000:3000 decker

You should then be able to access Decker in your web browser at http://127.0.0.1:3000/build/decker.html.

Casa-OS Integration

You can integrate directly with Casa-OS by using the Decker.yaml file. In Casa-OS, add a new app (a plus button in the upper right corner of the App section), and select Install a customized app. In the upper right corner there is a button which allows you to Import. Select this and load the Decker.yaml file within this repo. You can modify any of the parameters as needed. Click Install and after a few moments you should be able to access Decker by clicking on the Decker app that was installed. You can navagate directly to the URL

<your IP Address>:3001/decker.hml

Assuming you used the same 3001 mapping as in the yaml file.

Native-Decker

Decker is also available as a native application, written in C. Building Native-Decker from source requires:

• a c compiler and libc
• the xxd utility (standard with MacOS and most *nix distros)
• SDL2
• SDL2_image

On MacOS, BSD, or Linux, fetch the appropriate SDL2 packages and then build with make. This has also been reported to build and run successfully under WSL:

brew install sdl2 sdl2_image                                   # MacOS/Homebrew
sudo apt install libsdl2-2.0-0 libsdl2-dev libsdl2-image-dev   # Debian
nix-shell                                                      # Nix

make lilt            # (optional) command-line tools
make docs            # (optional) build documentation (requires Lilt)
make decker          # build decker itself
make test            # (optional) regression test suite
sudo make install    # (optional) install lilt, decker, and lil syntax profiles

If SDL2 is not available, Native-Decker can also be built with reduced functionality against SDL1.2 and a corresponding version of SDL_image. This compatibility shim is presently designed with the OLPC XO-4 and its default Fedora 18 OS image in mind; expect to do some tinkering with the makefile for other platforms:

sudo yum install SDL-devel SDL_image-devel

make decker

Lilt

Decker's scripting language, Lil, is available as a standalone interpreter, with extended IO functionality to make it suitable for general-purpose programming and scripting: this package is called Lilt. Lilt only requires libc and xxd to build from source:

make lilt

Lilt can be used to programmatically create, inspect, and manipulate decks, as well as package them as Web-Decker self-executing documents:

$ lilt
 d:read["examples/decks/color.deck"]
<deck>
 d.card:d.cards.colhex
<card>
 d.card.widgets.hex.text:"FFAA00"
"FFAA00"
 d.card.widgets.hex.event["change"]
0
 d.card.widgets.rgb.text
"16755200"
 write["color.html" d]
1

You can build Lilt against Cosmopolitan Libc, producing a single binary that will run on most popular operating systems:

$ ./apelilt.sh
successfully compiled lilt.com
running tests against ./lilt.com...
all interpreter tests passed.
all dom tests passed.
all roundtrip tests passed.

$ sh ./lilt.com
  range 10
(0,1,2,3,4,5,6,7,8,9)

The Danger Zone

Decker normally sandboxes the execution of scripts within decks to prevent low-level access to the host computer and ensure parity between the capabilities of Web-Decker and Native-Decker. Both implementations offer opt-in APIs for performing more "dangerous" or non-portable operations called The Danger Zone.

When building Native-Decker from source, you can enable The Danger Zone by defining the DANGER_ZONE preprocessor flag:

FLAGS:=$(FLAGS) -DDANGER_ZONE

A "dangerous" build of Native-Decker can export "dangerous" Web-Decker builds. You can also temporarily enable The Danger Zone for Web-Decker by calling the endanger() function from your browser's JavaScript console or modifying the DANGEROUS=0 constant in the .html file to DANGEROUS=1. The Forbidden Library offers a suite of bindings for useful JavaScript APIs based on this interface.

Contributing

The Decker project is released under the MIT license. Any contributions to this repository are understood to fall under the same license.

• Bug fixes and typo corrections are always welcome.
• Bug reports must include simple steps for reproduction and clearly indicate the OS and/or web browser where the bug arises.
• PRs should match the style of existing code.
• PRs should be as small as possible, and must not contain bundled unrelated changes.
• PRs must include updates for both the C and JavaScript versions of Decker (or its associated tools) whenever relevant.
• PRs must include updates for documentation (see: the docs directory) wherever relevant.
• PRs must pass the entire test suite (see: make test/make testjs).
• PRs must not incorporate any material generated by or with the assistance of any so-called "generative AI" tool or language model. Place your trash in an appropriate receptacle.
• When modifying the JavaScript version of Decker, please test your changes in multiple web browsers and avoid using bleeding-edge features. As a rule of thumb, if it didn't exist 5 years ago, don't use it now. If it only works in Chrome, it's better not to do it at all.
• When modifying the C version of Decker, avoid generating warnings and do not use compiler-specific features such as GCC extensions.

Please refrain from submitting Pull Requests to this repository containing new features without first discussing their inclusion in an Issue. Decker is intended to be small, simple, and cozy. There are an infinite number of features that could potentially be added, but creative constraints are also valuable. If you have a differing vision, feel empowered to explore it in your own fork of the project- that's what permissive licenses are for.

Contact

John Earnest jearnest@gmail.com http://beyondloom.com