Originally written for Bussard, the spaceflight programming adventure.
Important Note: Polywell is in the process of being ported to the Fennel programming language, so the master branch is a bit unstable and the docs aren't always right. Try 1b049fc as the latest commit before Fennel was introduced in the unlikely event that you need something stable and can't wait.
To say that Polywell is an editor is a little bit misleading; it may be better to think of it as an interface that allows in-game coding either to tighten the feedback loop during development or allow the player to take their customizations to the next level by writing their own code that calls functions from a sandboxed game API. But its mode-based keybinding system can also be used as controls for your game.
Polywell comes with example config which defines a special editor mode
that works as a Lua console. However, none of that is hard-coded in;
the console mode simply binds the
enter key to a function which
loadstring on the provided input and prints the return
value. But you can build many kinds of text-centric interfaces using
Polywell buffers; for instance the game Bussard includes a
mail reading interface
as well as a simulated SSH client.
The ideal means of user empowerment is to give your users the same tools inside the program that you used to create the program yourself; this is the vision behind Polywell.
Emacs key bindings (optional)
TODO: smarter lua-aware indentation
TODO: fuzzy-matching opening files and switching buffers
There are basically three ways to use Polywell. You can use it as a
standalone Lua text editor by just running
love . in
your project directory. You can also embed it in your game in order to
allow you to write your game
from the inside out as it were, and
experiment with changes to the code directly while running the game
and reloading. See the game
Liquid Runner for an
example of a game written from inside Polywell. Finally, you can embed
it in your game inside a sandboxed evaluation context and integrate it
into your game in a way that allows the game's players to write their
own code that can control the game. See
Bussard for an example of a
game that does this. There is also a
sandbox_example.lua file which
shows a simpler example of how to do this.
If you have a
~/.polywell/init.lua file, then standalone Polywell
will load that first, but if you don't, it will fall back to the
defaults in the
config directory. There are separate files for a lua
console, lua-specific code colorization, and Emacs key bindings.
Using Polywell for in-game coding can be a bit tricky because typical Lua
idioms often make reloading difficult. You have to be very intentional
about keeping all your state in a single table and have some mechanism
to replace all the functions without resetting the state. The
lume.hotswap function may be useful here.
See the reference manual for more detailed coverage of Polywell's API.
If you don't have luafilesystem then the editor will work, but the completion when you try to open new files will be inoperable.
The required dependencies are already included in the Polywell source.
TODO: package properly with luarocks
Copyright © 2015-2018 Phil Hagelberg
Released under the terms of the GNU Lesser General Public License version 3 or later; see the file LICENSE.