bitsy hacks

npm i @bitsy/hecks

A collection of re-usable scripts for Adam Le Doux's Bitsy Game Maker. See Ayolland's Borksy for a GUI that allows you to use these hacks with less copy-pasting.

Last tested against Bitsy 8.12

Contents
How to use
FAQ
Old Versions
Further reading

👥 avatar by room: change the avatar in certain rooms
🖼 backdrops: makes the game have a backdrop
🔈 basic sfx: "walk" and "talk" sound effect support
😌 bitsymuse: A variety of Bitsy sound and music handlers
😴 canvas replacement: WebGLazy bitsy integration (this one's mostly just for me)
😽 character portraits: high quality anime jpegs (or pngs i guess)
🙀 character portraits animated: high quality anime gifs
⛔️ close on ending: Prevents from playing past an ending
➿ corrupt: corrupts gamedata at runtime
🎞 custom-exit-effects: make custom exit transition effects
🅰 custom text effect: make {custom}text effects{custom}
💬 dialog audio: animal crossing-style audio
🎺 dialog audio vocal synth: animal crossing-style audio powered by the pink trombone vocal synth
🔁 dialog box transition: adds an easing transition animation to display the dialog box text
🔀 dialog choices: dialog choices
🚀 dialog jump: jump from one dialog entry to another
💬 dialog pause: add pauses in between printing text
⌨ dialog prompt: prompt the user for text input in dialog
↔ directional avatar: flips the player's sprite based on directional movement
🔝 direction in dialog: provides a variable with player direction
🖼 dynamic background: HTML background matching bitsy background
📝 edit dialog from dialog: edit dialog from dialog (yes really)
🖌 edit image from dialog: edit sprites, items, and tiles from dialog
👯‍♂️ edit player from dialog: change which sprite is controlled by the player
🏠 edit room from dialog: modify the content of a room from dialog
🔚 end-from-dialog: trigger an ending from dialog, including narration text (deprecated)
🚪 exit-from-dialog: exit to another room from dialog, including conditionals
🛰 external-game-data: separate Bitsy game data from your (modded) HTML for easier development
🌐 favicon-from-sprite: generate a browser favicon (tab icon) from a Bitsy sprite, including animation!
💕 follower: make sprites follow the player
🎮 gamepad input: HTML5 gamepad support
🍂 gravity: Pseudo-platforming/gravity/physics
🕷 itsy-bitsy: for when bitsy's not small enough
☕ javascript dialog: execute arbitrary javascript from dialog
🔀 logic-operators-extended: adds conditional logic operators
📜 long dialog: put more words onscreen
👨‍👨‍👧‍👧 multi-sprite avatar: make the player big
🔄 online: multiplayer bitsy
⬛ opaque tiles: tiles which hide the player
📃 paragraph-break: Adds paragraph breaks to the dialogue parser
⏳ permanent items: prevent some items from being picked up
➡ push sprites: sokoban-style sprite pushing
🎭 replace drawing: add name-tags to replace drawings when the game is loading
💾 save: save/load your game
🛑 solid items: treat some items like sprites that can be placed multiple times
⏱️ stopwatch: time player actions
🗣 text-to-speech: text-to-speech for bitsy dialog
🏰 tracery processing: process all dialog text with a tracery grammar
🎞 transitions: customizable WebGL transitions
🔳 transparent background: makes the game have a transparent background
👁️‍🗨️ transparent dialog: makes the dialog box have a transparent background
🏁 transparent sprites: makes all sprites have transparent backgrounds (deprecated)
💱 twine bitsy comms: interprocess communication for twine and bitsy
❄ unique items: items which, when picked up, remove all other instances of that item from the game

How to use

Each script has a short "HOW TO USE" section included in the comments. For steps which say to Copy-paste this script into a script tag after the bitsy source, open your exported bitsy game and scroll to the bottom of the file (at the time of writing, it looks like this):

</script>

</head>


<!-- DOCUMENT BODY -->
<body onload='startExportedGame()'>
  <!-- GAME CANVAS -->
  <canvas id='game'></canvas>
</body>


</html>

then edit it to look like this:

</script>

<script>
  // and then paste your code here!
</script>

</head>


<!-- DOCUMENT BODY -->
<body onload='startExportedGame()'>
  <!-- GAME CANVAS -->
  <canvas id='game'></canvas>
</body>


</html>

FAQ

I don't know javascript. Can I still use the hacks?

Yes, most of the hacks require little to no javascript experience.
Can I import a hacked file back into the Bitsy editor?

Yes, but unfortunately only the gamedata will be imported, and the hacks will be lost. To edit a hacked game, it's recommended that you keep a copy of the hacked html file, and copy-paste edited gamedata into it. If you need to do this a lot, there are a few tools available to speed up your workflow (e.g. bitsy-savior, Borksy, bitsy-boilerplate).
Some of these hack files are kinda long. Do I need to copy the whole thing?

Yes, you need the entire hack file in order for it to work. If for some reason you're really concerned with filesize (you shouldn't be), you can programmatically compose and minify them (either by cloning this repo or by using the bitsy-boilerplate project), but this is only recommended for developers familiar with javascript bundling.
Can I combine multiple hacks?

Yes, but there are known issues with specific combinations. If you're having issues using multiple hacks, try testing them one at a time to make sure they've each been setup correctly.
Do the hacks work with forks like Bitsy 3D, Bitsy HD, or Bitsy Color?

It varies by hack and by fork. If something doesn't work, try testing against a regular Bitsy game to make sure you've setup the hack correctly.

Bitsy HD in particular is a fairly old fork, and generally needs older versions of hacks.
Do the hacks work with emulators like bitsy boutique or bitsybox?

No. Emulators function by re-implementing parts of the engine and/or browser into another environment, but the hacks rely heavily on how the engine is structured and how the browser handles <script> tags. However, desktop projects which preserve the original engine/browser context (e.g. Electron, NW.js) can be used.

If your question isn't covered here, it may be in the general Bitsy documentation.

For other issues, feel free to open an issue, contact me directly, or ask for help on the Bitsy forum!

Old Versions

Bitsy and the hacks are generally not backwards-compatible: when Bitsy updates, it often breaks individual hacks. If you're having issues with hacks after a Bitsy update, it's possible they are out of date. Feel free to reach out for help or open an issue if you suspect this is the case.

If you are using an older version of Bitsy (or a fork based on an older version), you may require old versions of the hacks. Support is not guaranteed across versions, and old versions are not maintained, but some helpful points in history are listed below.