An example repo that shows a simple game of Pong -- with all the tools needed to read and modify its inner workings.
Install LÖVE. It's just a 5MB download, open-source and
extremely well-behaved. I'll assume below that you can invoke it using the
love command, but that might vary depending on your OS.
Download this repo:
git clone https://git.sr.ht/~akkartik/pong.love pong
Run the game:
When you want to read or modify the game, open up its editor by pressing
ctrl+e. (Check out more keyboard shortcuts below to see what you can do.)
When you're done reading or making changes, press
ctrl+e again to play Pong
with any changes you made.
Keyboard shortcuts: playing Pong
At the start, press any key to start a game. Once a game starts:
zto move the left-hand paddle
downto move the right-hand paddle
spaceto start a new game
ctrl+eto stop playing and browse the code for the game
Keyboard shortcuts: reading source code for Pong
ctrl+eto go back to playing Pong, using any changes you made
ctrl+gto switch to a different file
ctrl+lto toggle a second editor on the right for recent logs. Useful when debugging.
ctrl+=to zoom in,
ctrl+-to zoom out,
ctrl+0to reset zoom
On the left (source code) side:
ctrl+fto find patterns within the current file
alt+leftto jump to the next/previous word, respectively
- mouse drag or
shift+ movement to select text,
ctrl+ato select all
ctrl+eto modify the sources
Exclusively tested so far with a US keyboard layout. If you use a different layout, please let me know if things worked, or if you found anything amiss: http://akkartik.name/contact
The primary method here to understand what Pong is doing (or indeed any other
program you choose to turn this repo into) is the log. To emit objects to the
log, use the
log(2, "log message")
log takes exactly 2 arguments: a stack frame index to report the file and
line number for, and an object to log.
The stack frame index should be
2 if you call
log directly. If you create
higher levels of abstraction around
log, increment the stack frame
log should use a stack frame index of
to report line numbers from its caller. Helper
should use a stack frame index of
4, and so on.
log function can only emit a single object at a time. However, the
object can be of any type.
Since each entry/line in the log contains a single object (after the filename
and line number), it's easy to specify how different objects should be
rendered. Just make sure the objects contain a field called
name, and create
log_render.name to render it. In this repo, the function
log_render.state is an example of such a function, specifying how to render
a Pong state consisting of a ball position, ball velocity and paddle
Rendering functions must all have the same interface as
function log_render.state(state, x,y, w) ... end
The first argument is the object that was logged, the remaining arguments specify the starting position from which to render it, and the width on screen available to it. After the function finishes rendering the object, it should return the y coordinate it drew until, so that the log browser knows where to start rendering the next object.
Sharing your changes
While pong.love lets you make changes to its source and shows how your changes affect its behavior, the changes don't live in the same place as the original sources. They live in the app's save directory (love.filesystem.getSaveDirectory()).
To distribute your version you'll need to copy the modified files over into the app, either its directory or its .love zip archive. This process is [unfortunately not automated yet](See https://love2d.org/wiki/Game_Distribution).
Mirrors and Forks
This repo is a fork of lines.love, an editor for plain text where you can also seamlessly insert line drawings. Its immediate upstream is text.love, a version without support for line drawings. Updates to it can be downloaded from:
- https://nest.pijul.com/akkartik/pong.love (using the Pijul version control system)
Further forks are encouraged. If you show me your fork, I'll link to it here.