Boulder Dash Forum

Boulder Caves+ - An enhanced, bug-fixed, Krissz Engine compatible Boulder Dash remake written in Python 3 and based on Boulder Caves by Irmen de Jong.

Current version: 1.1.4
DOWNLOAD HERE (GitHub repository)

Please make sure you read the enclosed README and FAQ files for additional information regarding the game.

To start the game, use the "launcher.py" file.
Please make sure you have the following components installed before playing:
* Python v3.6 (or newer) and the following libraries:
- Tkinter
- PIL (or Pillow)
- Synthplayer
- Miniaudio

Check the enclosed README for additional details regarding installation of the game.

The game comes bundled with an improved Construction Kit and with KrisszConvert, a tool to convert graphical images of caves from Krissz Engine into a compatible BDCFF representation playable in Boulder Caves+. If you're interested, check the README file in the "tools" folder to learn how to use this tool.

Boulder Caves+ is based on Boulder Caves by Irmen de Jong. You can find the original version of his game here.

Boulder Dash (tm) is (C) 1984 First Star Software, created by Peter Liepa and Chris Gray.
The Boulder Dash franchise currently belongs to BBG Entertainment GmbH, all rights reserved.
Boulder Caves+ is a free and open source, non-commercial, non-profit fan made software released under GNU GPL v3.

Standard Boulder Dash tile set is based on the original graphics of Boulder Dash by Peter Liepa and Chris Gray, as represented in GDash.
Modern tile set is from MIT-licensed GDash and is based on Boulder Rush by Michael Kowalski / Miksoft.
Krissz Engine tile set extensions, as well as the extra boulder sound, are by Krissz.
All fan-made object artwork is courtesy of its original authors.
All fan-made caves bundled with Boulder Caves+ are courtesy of their respective authors, as credited in the BDCFF cave files and as seen on the gameplay screen when the cave is loaded.

If you are the author of some of the enclosed material (graphics, sounds, or caves) and you object to your content being distributed with Boulder Caves+, please contact me and I'll remove your content from the distribution and, if necessary, replace it with the alternative content.

Have fun!

- Agetian

Boulder Caves+ Frequently Asked Questions

Q: What is Boulder Caves+?
A: Boulder Caves+ is a Boulder Dash clone/remake written in Python 3 and based on Boulder Caves v5.7.2 by Irmen de Jong. Essentially, it's a Boulder Caves fork that offers many bug fixes and mechanics improvements compared to the original, making the game closer to the reference Boulder Dash rule set implementation, and is also the first Boulder Dash remake to offer compatibility with Krissz Engine, a closed source, limited access online engine made by Krissz. A conversion tool is bundled with the game to aid in converting caves from Krissz Engine for use with Boulder Caves+. Boulder Caves+ also comes with an improved and bug-fixed Boulder Caves editor, renamed to Construction Kit for consistency with other BD engines, that allows you to design your own caves or edit the existing ones. Boulder Caves+ also has a simple UI-based graphics launcher to simplify setting the common game options.

Q: Why was Krissz Engine chosen as a target for a clone implementation?
A: Krissz Engine represents the current generation of actively maintained Boulder Dash clones and boasts a database of over 15000 unique caves with many brilliant design ideas implemented in a time span of 7 years (as of 2021) by some of the best Boulder Dash cave designers, which, in my opinion, makes this engine a highly important one. It is also an unquestionably high quality engine with traditional Commodore 64 style graphics and with many interesting features that are harmoniously integrated on top of a standard Boulder Dash I/II rule set core and extend it in unobstructive and believable ways that do not contradict the fact that you're still playing Boulder Dash and not some other puzzle game. At the same time, unfortunately, it's also one of the most closed implementations of Boulder Dash in existence, being a closed source engine running on an online-only service with restricted access. The engine author appears to be very protective of the exclusivity of these caves to the engine, and it is possible, albeit not certain, that the service may intentionally be designed in a way that hinders possible export. The only export options available in the engine are essentally screenshots, taken from either the Construction Kit or from a cave preview image, with some of the elements not represented in full (e.g. the inbox, the outbox, the magic walls are not visible on the cave snapshots or semi-cloned caves). Due to all the outlined circumstances, not only are a very limited number of people aware of the existence of the engine and are able to access it, there is also a concern regarding the long-term perspectives for the engine, as it's unclear what would happen if its author decides to shut down the website at some point in the future, or if the service is shut down for any other reason, possibly beyond the author's control. Several people started building up collections of cave images from Krissz Engine for preservation purposes, as documented on Arno's Boulder Dash fan forum, and Arno himself also makes regular videos of some of the best caves to document this experience. All of this is a good and commendable effort, but in the long run, unless Krissz plans to publicly release the cave database and possibly the engine source code when the online service is closed down, years of hard work by multiple devoted fans of Boulder Dash will be at risk of being forever lost to history, with little to no way for the possible future generations of Boulder Dash fans to experience this amazing work except through Arno's videos and possible image-based recreations. Boulder Caves+ aims to attempt to prevent this unfortunate outcome by providing the fans with an open source engine and a conversion toolset that would allow preservation of Krissz Engine caves in a portable exchange format based on the BDCFF specification through optical image recognition of cave snapshots and cave images taken from Krissz Engine Construction Kit. Boulder Caves+ may also pave the way for more compatible implementations to be made in the future. It will, of course, be up to the cave authors themselves to make the cave conversions and then either reserve them for personal use or release them to public in some form. Therefore, ultimately, the preservation of Krissz Engine caves and their public availability depends on the cave authors themselves, as it should be, with Boulder Caves+ being the first targeted tool and engine in existence (but possibly and hopefully not the last one) that specifically targets Krissz Engine compatiblity and can aid in working towards this goal.

Q: What platforms does Boulder Caves+ run on?
A: Similar to the original Boulder Caves, Boulder Caves+ is cross-platform and was tested to work on several different Linux distributions and on Microsoft Windows 10. It should also run on MacOS with relative ease, but wasn't tested on this platform so far due to the inavailability of the platform to the developer.

Q: What are the minimum system requirements for Boulder Caves+?
A: Speaking of the low-end hardware that performed relatively well with the game and may be an indication of what the minimum system requirements are, Boulder Caves+ was tested to have acceptable performance in most tested caves on an overclocked 2 GHz Raspberry Pi 4 B+ with 4 GB RAM. Except for very big caves with a lot of dynamic objects, it was possible to play the game in either 60 fps or 30 fps mode in full screen without needing to turn on many (or any) optimization options. Therefore, any relatively recent (5-7 year old) PC with a midrange CPU should be able to play BoulderCaves+ with little to no difficulty and without any limitations. The weakest hardware the game was tested on was a Raspberry Pi 3 with 1 GB RAM. The game was rather playable with standard-sized (40x22) or smaller caves (intermissions and mini caves) in 30 fps mode, but would grind to a halt and even hang on bigger (e.g. 60x60, 80x80) and "busier" caves, even with all optimization options enabled. It's not clear whether it was due to the CPU performance or the lack of RAM or both, but pretty obviously, Raspberry Pi 3 does not make a good target for playing Boulder Caves+ unless you only plan to play simpler and smaller-sized caves.

Q: What software is required to run Boulder Caves+?
A: In order to run Boulder Caves+ on your PC, you need Python v3.6 or newer installed, and you need the following libraries, all of which can easily be installed using Pip, a command line Python package manager that usually comes bundled with the modern Python 3 versions or can be installed from your software repository:
* Tkinter (may come bundled with your Python 3 installation)
* Pillow (or PIL)
* Synthplayer
* Miniaudio

Q: I played the original Boulder Caves and it was quite slow and buggy. Is Boulder Caves+ going to suffer from the same problems?
A: Boulder Caves+ is a heavily modified and partially rewritten version of Boulder Caves, with multiple bugs and optimization issues from the original fixed. While it may have its own share of issues, it's a different project and you shouldn't expect the same problems or the same performance as the original Boulder Caves. Due to the heavy rework, the original Boulder Caves should not be taken as an indication of how Boulder Caves+ will play or perform. Therefore, you're advised to give Boulder Caves+ a try and see if you deem it playable on your machine or not, regardless of what experience you may have had with the original Boulder Caves.

Q: Why does Boulder Caves+ use Tkinter and Pillow for graphics? Wouldn't it be a better choice to use SDL 2 / Pygame 2?
A: Yes, it would have been a better design choice to use Pygame 2.x based on SDL 2, which is faster than the Tkinter/Pillow graphics chain. However, the original BoulderCaves implementation by Irmen de Jong uses Tkinter/Pillow, and this choice was "inherited" for now by Boulder Caves+. There are plans to attempt to port the game to SDL 2 (Pygame 2.x), but it's a long-term plan which will only be implemented once other development targets are met. Porting the game to SDL 2 will likely bring additional performance benefits and may further reduce minimum system requirements, but I don't expect major breakthroughs in performance compared to the current implementation, because in most tested conditions, the bottleneck wasn't the graphics display, but the ability to perform a per-frame cave scan in a timely manner, especially in bigger caves with thousands of objects scanned per frame.

Q: What caves does Boulder Caves+ come bundled with?
A: Boulder Caves+ comes bundled with the standard cave set representing Boulder Dash I by Piter Liepa and Chris Gray, which it inherits from the original Boulder Caves. Also, four cave sets that were distributed with the original Boulder Caves (Arno Dash 01, Firefox 01, Sendy Dash 01, and irmen) are still distributed with Boulder Caves+ and can be found under the "BoulderCaves Bundle" category in the launcher. On top of that, Boulder Caves+ comes with several dozen Krissz Engine cave conversions, categorized by author, as a demonstration of the Boulder Caves+ clone engine capabilities and the capabilities of the KrisszConvert conversion tool. These caves are categorized by author in the game launcher.

Q: How do I get additional caves for Boulder Caves+? Where can I find additional Krissz Engine caves?
A: If you're interested in Krissz Engine caves, unfortunately, due to the closed nature of the engine and the website, there is no way to download or export a cave from the engine except for saving cave snapshots and images, and there is no way to access the engine for someone who is not registered at Krissz's website. Therefore, you would have to rely on cave authors who make caves for Krissz Engine to make their own custom exports using the provided conversion tool and then share those caves with the community at various websites dedicated to Boulder Dash. If you have access to Krissz Engine, you can export your own caves or the caves you like by other authors by (semi-)cloning them, editing them to properly have all the elements, then saving the cave image from the Krissz Engine Construction Kit and processing the image using KrisszConvert, a converter bundled with Boulder Caves+. You will also need to manually set the cave properties to match the properties in Krissz Engine. Please check the README file in the "tools" folder for details about how to perform the conversion of your Krissz Engine caves for preservation and use with Boulder Caves+.
A: In addition to Krissz Engine caves, Boulder Caves+ has limited compatibility with various other cave sets stored in BDCFF format - many are available, for example, at Arno's website in the Game Base section. Note that only the "simpler" BDCFF cave sets without any non-standard elements and without any non-standard or "exotic" options will be supported. For example, advanced GDash cave sets which use various custom objects and options will not work correctly and may not work at all. To play these cave sets, please use a different engine such as GDash.
* Please note that any caves you would like to use in Boulder Caves+ will need to be placed into the "caves" folder of the game or one of its subfolders. You can categorize the caves in subfolders by author, type, or category as you see fit. Subfolders within subfolders are currently not supported.

Q: Is Boulder Caves+ fully compatible with the New Krissz Engine?
A: Boulder Caves+ is designed with New Engine compatibility in mind as a priority task, and should be able to play many, and hopefully most, caves designed for the New Krissz Engine as of December 2021. However, due to the closed source nature of Krissz Engine, it's challenging to learn about the minute details of the functioning of the engine, especially when it comes to "side effects" and corner cases. Therefore, certain functionality in Boulder Caves+ may not yet match the New Engine perfectly, and as such, some caves that rely on these unimplemented side effects may not yet be completable. Hopefully there are not many cases like that, and it's the intent to flesh out the implementation over time for compatibility with as many caves as would be possible. Please also note that some features might differ slightly or not be a perfect representation of the relevant features in Krissz Engine - for example, infinite scroll is not yet perfectly implemented and is slightly jerky when crossing the open border.

Q: Is Boulder Caves+ fully compatible with the Old Krissz Engine?
A: While Boulder Caves+ is not designed with Old Engine compatibility in mind, at least as a priority task, it should be able to load and play Old Engine caves if they are converted using KrisszConvert using the same procedure as for any other Krissz Engine cave. However, Old Engine, as far as I know, is somewhat substandard in how the cave scanning is performed, which may create unique corner cases in game mechanics that are not standard to other reference implementations, including the New Engine and GDash. I couldn't find any information detailing this difference, and it's impossible to learn about the relevant algorithm because the engine is closed source and there's no Construction Kit available anymore that would allow to design caves for the Old Engine in order to test functionality. As such, if there are caves for Old Engine that rely on this special, unique functionality and the side effects that it brings about, these caves are unlikely to work correctly in Boulder Caves+ and will most likely not be completable. Also, there's very little chance that there will be targeted improvements in this area in the future in order to support these side effects. However, any standard cave that doesn't depend on functionality that is unique to Old Engine should be loadable and hopefully completable with Boulder Caves+.

Q: Is Boulder Caves+ fully compatible with the original Boulder Caves?
A: Yes, Boulder Caves+ should still be able to load any cave or cave set that the original Boulder Caves by Irmen de Jong can load. The only differences you will notice are the fixed bugs and mechanical functionality improvements. If you find a cave set that works in Boulder Caves but doesn't work in Boulder Caves+, it's most certainly a bug that needs to be fixed.

Q: Are there any features in Boulder Caves+ beyond the features supported by Krissz Engine?
A: Yes, on top of being able to work in a Krissz Engine compatible manner, Boulder Caves+ also supports a number of features that it inherits from the original Boulder Caves which allow it to offer extended functionality. For example, caves are not limited to a 4-color palette, and you can use a full 7-color Commodore 64 style palette, e.g. with a unique color for amoeba and slime. Also, you're not limited to a single life or to a single cave per set, you can merge several caves, even converted Krissz Engine caves, into a cave set that starts with 3 lives and allows bonus lives to be earned, and Boulder Caves+ will happily play the cave set in this form. Several BDCFF cave options are supported that are not Krissz Engine-compatible, for example, the amoeba ratio can be defined fractionally, and unpredictable slime permeability is supported in addition to the Krissz Engine predictable slime permeability. Line shift is supported, which is an option supported by, for example, GDash that shifts Rockford to the next cave row when the open horizontal border is crossed. Intermissions are supported in cave sets, which are essentially single-attempt small bonus caves.

Q: Are there any plans to add any custom objects to Boulder Caves+, such as biters, ghosts, and keys, similar to GDash?
A: There are currently no plans to implement custom objects in Boulder Caves+, at least until other priorities are complete to the maximum possible degree. However, some of the simpler custom objects such as alternate fireflies/butterflies, biters, and possibly alternate graphics sets such as the Boulder Dash III style "space" tile set, may be considered for future implementation if time permits.

Q: Is there any way to contribute to Boulder Caves+?
A: Boulder Caves+ is an open source project published in a public repository at Github. Code contributions and improvements are welcome. You are also welcome to start your own fork if you feel the need to, the only thing I'm asking about is that you adhere to the GNU General Public License v3 terms that the project is released under and that you properly give credit to the authors of the original projects, not only Boulder Caves+, but also Boulder Caves which it is based on.

Q: Do you accept donations for Boulder Caves+?
A: No, Boulder Caves+ is a strictly non-commercial, non-profit fan product. Like any other Boulder Dash clone or remake made by a third party, it is my strict opinion that it should not be commercialized in any way, being based on a franchise that does not belong to me or to anyone else in the fan community. Therefore, please do not offer any form of payment for the game, even in the form of a voluntary donation. If you would like to make a donation to the Boulder Caves+ project, please instead consider making a donation to any of the existing charities that you would find appropriate for you. That will benefit many people, possibly even someone who is close to the author of this project, and would therefore be an indirect contribution to the well-being of people involved in the project.

Ok, my first progress report

The project priorities are as follows:
1. Krissz Engine compatibility to the best of my ability, eventually aiming for a frame exact implementation, if at all possible. The ultimate goal is to have an open-source implementation of a BD engine that would be able to play maps originally designed for the Krissz Engine offline, in as authentic a way as would be feasible for my implementation. Also, the aim is to provide a tool that would aid in converting a Krissz Engine map to an extended BDCFF representation for use in this engine. Conversion will be based on a PNG source representing the map, as exported from Krissz Engine construction kit. Krissz Engine compatibility and conversion are top priorities, and the aim is to allow preservation of caves created for Krissz Engine for the future, and to provide some kind of a reference for which features exist in the engine in case the online engine ceases to exist at some point, so that the caves can be preserved and played and eventually better compatible implementations could be figured out and written.
2. Mechanical correctness, aiming to fix the issues and improve the gameplay precision compared to the original BoulderCaves implementation (which, unfortunately, suffers from several major issues and implementation problems). Ideally, the game should be playable in as close of a way to the original and Krissz Engine mechanics as would be possible to develop.
3. Improved bundled editor, supporting the addition of all new objects not in BD1, BD2, or BoulderCaves (e.g. Light Boulder, Heavy Boulder, two-way Expanding Wall), as well as specifying all Krissz Engine specific cave properties such as No Time Limit, Reverse Time, Open Horizontal/Vertical Borders, Value of a Second, among others.

The current state of the project is as follows:
- A number of important bug fixes making this engine closer to the original mechanics and preventing crashes:
- Fixed a critical issue with tile grab causing a full second Rockford movement delay when trying to switch direction.
- Fixed an issue which made it possible to grab (illegally) a diamond that is falling on Rockford's head by moving/grabbing up.
- Fixed an issue which allowed the player to try to push a falling object (appears to be illegal according to GDash source).
- Fixed a crash when an unsupported letter/character is present in the cave name or in the high score player name.
- Fixed a crash when trying to play a cave larger than the screen area in a smaller window.
- Fixed the game "spoiling" the location of expanding walls by showing them with special icons while in game (there's still an option to go back to the original BoulderCaves behavior where expanding walls are marked).
- Fixed not being able to snap-activate an outbox.
- Fixed the slime not evaluated properly in BoulderCaves (was evaluated while scanning the falling object instead of the slime itself, preventing the implementation of proper permeability).
- Fixed the ability to press ESC to explode after the level is won.
- Fixed (mostly) Rockford idle blinking animation to at least not break up continuously. Still needs proper syncing to the beginning of the animation cycle (per GDash source code).
- Fixed Amoeba never switching from slow growth to fast growth on certain property values and frame rate settings.
- Fixed the push chance being half of what it should be (per GDash source code, seems to be matched by Krissz Engine).
- Fixed Rockford switching to movement animation even if he won't move this frame due to a missed cave scan update.
- Fixed the bonus life background animation not properly syncing up across the entire cave.
- Fixed the wraparound and lineshift implementations to match GDash / CLCK developer documentation.
- Implemented centering for smaller maps, it was supposed to work in the original BoulderCaves but was partially broken and incomplete.
- Implemented wraparound and lineshift functionality similar to GDash, the original BoulderCaves implementation did not seem to behave according to the BDCFF specification documentation.
- Implemented the Krissz engine icon for slime as an alternate tile when in Krissz Engine compatibility mode.
- Implemented the PLCK/Krissz engine-compatible slime permeability behavior based on the C64 predictable random number generator and PLCK permeability patterns.
- Implemented continuous Rockford animation when the cave is won (per original/GDash/Krissz implementations), with an option to go back to the original BoulderCaves behavior (stationary Rockford).
- Implemented per-frame final score count as opposed to the choppy 5-point one (similar to original/GDash/Krissz implementations), with an option to go back to the original BoulderCaves behavior.
- Implemented the C64-style (also GDash/Krissz style) three-digit seconds timer as default, with an option to go back to the BoulderCaves style displaying the timer in minutes and seconds.
- Implemented the proper playback of a quick succession of timeout sounds when the timer counts down to 0 at the end of level.
- Implemented visual cave centering for smaller caves.
- Implemented the C64/GDash/Krissz style cell animation during the cave reveal demo.
- Implemented the C64/GDash/Krissz style yellow-colored diamond count in the score sheet.
- Implemented Krissz Engine style Voodoo Rockford behavior (when in compatibility mode).
- Implemented several more icons styled after Krissz Engine (e.g. the Voodoo Rockford looks like Rockford when in Krissz Engine compatibility mode)

- A considerable number of features from Krissz's online Boulder Dash engine implementation are implemented, making BoulderCaves+ support a significant number of caves for that engine:
- Light Boulder is implemented in as close a way to the Krissz engine mechanics as I could figure out (pure CSO implementation).
- Heavy Boulder is implemented.
- Bidirectional Expanding Wall is implemented.
- Open Horizontal Borders and Open Vertical Borders options are implemented (both can be enabled at the same time). Instead of the "infinite cavern" implementation used on Krissz's website, BoulderCaves+ uses a simpler wrap-around implementation where you (and other objects) go in one way and out the other, jumping instantly to the focus cell if necessary (e.g. for wide caves).
- Game Speed in the number of frames per second is implemented (and is currently the only way to define the cave frame time in BoulderCaves+).
- Rockford Birth Time option is implemented.
- Amoeba Limit option is implemented.
- Value of a Second option is implemented.
- Magic Wall Stops Amoeba option is implemented.
- Amoeba Grows Before Spawn is implemented as an option and as a way to enable Krissz-style behavior where Amoeba starts growing before Rockford spawns.
- No Time Limit and Reverse Time options are implemented.
- Single Life option is implemented, to simulate the Krissz engine behavior where you only get one attempt at a cave before your high score is registered, and no extra lives are awarded as you play.
- Slime Permeability (PLCK) option is implemented, which is prioritized when set to a value between 0 and 8 and matches the Krissz Engine slime permeability values of 0 to 8, completely with impermeable slime patterns.
- Object animation speed is approximated to match Krissz's engine visually. May not be frame-perfect yet but is very close (seems to show the same frame time when tested in 60 fps mode and almost exact in 30 fps mode)

- The score bar approximates the behavior of Krissz Engine (e.g. the diamond count and requirement are marked in yellow color, the positioning of elements is similar)
- Extended the supported limits for the cave size and required diamonds compared to BoulderCaves.
- A simple window-based game launcher is available which allows to set the most common parameters and specify the cave or cave set to play (from the "caves" folder).

- Extended the bundled Editor with new features and quality of life changes:
- Introduced support for the new elements (light boulder, heavy boulder, Bidirectional expanding wall)
- The elements in the selection list are ordered and named the same way as in Krissz Engine
- Added toggles for all the Krissz-style cave options.
- Added a way to specify the initial direction for fireflies and butterflies (unfortunately, with no visual hint for now).
- Added a button that allows to set Krissz engine style defaults for the cave. Optionally sets the color palette that is used by default on Krissz Engine.
- Added a way to visualize the location and features of the element currently under cursor (currently shows the X/Y coordinates, direction (if applicable), and permeability (for slimes) in the title bar of the window)
- Added a button to visualize some basic cave statistics (the count of various elements in cave)
- Added Krissz Engine icons for the slime, inbox, outbox, and hidden outbox
- Added a way to visualize impermeable slime on the cave map (the Show Imperm button)
- Fixed a problem with the Save function not saving the cave name and description correctly
- Fixed an exception triggered when switching between modern and retro color palettes with an object selected in the tree view control

- Pypy3 support is figured out and tested (plays the mega.bd test at 30 fps without visible slowdown on my test PC).

- A simple cave converter is available which allows to convert caves from Krissz's engine to the BDCFF format based on the exported PNG image.
- Supports 32x32 tile cave preview images exported from Krissz Engine Construction Kit (preferred) and 16x16 tile cave snapshots saved by clicking the cave image in the cave list (less precise).
- Outputs a BoulderCaves+ compatible extended BDCFF map with proper colors (visually the same as in Krissz Engine), cave size, and a set of default parameters to be tweaked with values appropriate for the cave (based on the data from Krissz Engine Construction Kit or experimentation).
- Alternatively outputs a GDash compatible BDCFF map with proper colors and default values. This mode will not function in full if the cave contains Light Boulder(s) which are not supported by GDash.

The conversion tool is currently being developed, fine-tuned and tested, but essentially it takes an exported PNG representation of the map and converts it into an equivalent extended BDCFF representation that can then be tweaked/edited either manually or in the bundled cave editor and then played in the BoulderCaves+ engine. The converter is able to represent the map colors in a way so that they look identical in BoulderCaves+ as they look in Krissz Engine.

As of right now, the following caves have been converted to BoulderCaves+ and are confirmed to be fully playable and solvable, and they behave, look, and sound very similar to the way they do in Krissz Engine (within the limitations of what's currently implemented in BoulderCaves+ - e.g. instead of the infinite scroll, BoulderCaves+ currently uses an open border wraparound):

Max Diamonds Needed! (by Arno)
Blifil (by Altermaven)
Boulder Brothers (by Arno)
Diamond Shuffle (by Altermaven)
Trischi834 Big Church (by Trischi83)

Short-term goals
- Fix the remaining known issues, especially bigger ones that severely affect compatibility, improve engine precision and mechanical correctness based on studying the best open source implementations of the game currently available (e.g. GDash).
- Fine-tune, improve, and test the conversion tool, hopefully on a wide array of different maps with different sizes, colors, and elements. This will hopefully work out quickly enough with the contribution of exported PNGs from Arno.
- Establish a development repository, most likely a Git one (on Github), to enable public use of the engine and collaboration on playtesting and developing it, should there be any wider interest.
- Convert several more maps to BoulderCaves+ and ensure they can be completed.

Long-term goals (which may or may not work out)
- Implement bigger, more ambitious Krissz Engine-compatible features such as infinite scrolling in open borders mode.
- Port the game engine to SDL2 (from the current Pillow/Tkinter based UI and engine), possibly using Pygame 2.x, this might help optimize the visual output more (possibly allowing stable 60fps without the need for Pypy3?), increase keyboard responsiveness, add controller support, etc.
- Make the cave scanner frame-exact in all feasible respects, to improve compatibility with maps based on tricks that require precise timing. Will most likely go by GDash source code and developer documentation when tuning timing-based features.
- After BoulderCaves+ is feature-complete, possibly make an extended version of GDash supporting Krissz Engine objects (e.g. Light Boulder) and features (e.g. independent open borders, Reverse Time) that GDash doesn't yet support, making a Krissz Engine-compatible vesion of GDash as well based on the knowledge gained during the development of BoulderCaves+.

Screenshots
Here are some screenshots demonstrating the game in its current state.

1. Trischi83's "Big Church" as played in BoulderCaves+


2. Altermaven's "Diamond Shuffle" as played in BoulderCaves+


3. The extended bundled editor, showcasing Arno's "Boulder Brothers" in editor mode, complete with all the new objects and features from Krissz Engine. The BoulderCaves editor is pretty minimalistic, but it works. I aim to improve it a little as I develop the project further.


4. A very short video demonstration of Altermaven's "Blifil" running in BoulderCaves+. I suck at playing it though, lol, so it's just a short engine demo to show what it looks and sounds like when playing a Krissz Engine map.
A video on Dropbox

-------------------
Second report follows.

First of all, huge thanks to Arno for submitting a whole lot of cave snapshots taken from Krissz Engine for experimentation. Inspired by the immense amount of material, I spent a lot of time today fine-tuning my Krissz Engine conversion tool and teaching it to convert different PNG map layouts with different corner cases and whatnot. So far, it looks like I will be able to publicly release a version soon that will allow to convert basically any 4-tone or 3-tone map (I mean the one that uses a full 4-color palette or a 3-color one where the 4th color is the same as one of the other ones) to a BDCFF representation (either BoulderCaves+ extended representation or GDash style representation).

To give you an example of the conversion, here's the map "Arno 35" converted from the following PNG snapshot into the BDCFF format:



The BDCFF representation is as follows (cave parameters mostly omitted since thy're set to defaults anyway when a cave is converted):

Of course, *all* the cave parameters (time limit, diamond requirement, etc.) will be initially set to more-or-less BoulderCaves+ defaults, since obviously PNGs don’t contain any information regarding the cave frametime, time limit, open borders, or anything else. These parameters will need to be set manually in the converted BDCFF using a text editor or a compatible cave editor (e.g. the BoulderCaves+ editor).

The biggest issue with conversion is the fact that not all objects are uniquely represented on these PNGs — as opposed to the editor Cave Preview, the cave snapshots from the cave list not only preserve fewer objects, but also don’t preserve any information about the initial orientation of creatures (butterflies/fireflies). Thus, these BDCFF files are the closest approximation possible based on what’s available (visualized on the picture), but they may (and most certainly do) require manual tweaking to restore the original cave.

With the above in mind, for preservation purposes, there are three ‘’levels’’ of authenticity that can be established when using my conversion tool:

1. The best case scenario is when the author of the map himself makes a Cave Preview image from the Krissz Engine Construction Kit (by clicking the little icon image called ‘’Preview Cave Image’’), converts it to BDCFF, then manually specifies the parameters as needed. Because the author of the map sees all the elements in Construction Kit, every single one of them will be preserved on the PNG, and it’s also easy to copy the parameters from the Construction Kit into the BDCFF file.

2. The next preferred scenario is when someone (not the author of the map, for instance) who wants to preserve the map performs a Semi-clone on the map temporarily in Krissz Engine, then makes a Cave Preview. This preserves *most* objects (but not all — namely, outbox and magic wall / extending wall objects won’t be preserved) and it preserves butterfly and firefly orientation, and also allows to see some (but not all usually) of the original properties of the map. Thus, it’s still easier to convert the produced Cave Preview into BDCFF, then figure out where the outbox and the magic walls should be by playing the map or watching demos, and also figure out and specify the proper cave properties manually (partially based on what ends up in Construction Kit, and partially based on experimentation).

3. The last possible scenario is when someone (not the author of the map, for instance) simply takes a cave snapshot from Krissz Engine (by clicking the cave preview icon) and then converts that snapshot to BDCFF using my tool. Unfortunately, this is the most difficult case, because not only does this cave snapshot not preserve many objects (magic walls, outbox, extending walls, inbox vs. voodoo dolls distinction), it also does not preserve initial butterfly and firefly orientation (so, defaults will have to be assumed), and obviously, it’s impossible to deduce any of the cave properties without playing the game or seeing a demo on the video, since the cave is never loaded into Krissz Engine Construction Kit.

Therefore, if someone in our community would like to preserve his Krissz Engine maps in BDCFF format for playing in BoulderCaves+ or some other future Krissz-compatible engine that may eventually be made (e.g. I’m also planning to extend GDash with some Krissz Engine features later after I’m done with BoulderCaves+), the best option is exporting a Cave Image Preview from the in-game Construction Kit and noting (and specifying) the proper cave properties after conversion. This is generally the responsibility of the cave author who is willing to have a BDCFF-representable offline copy of the map for future use.

Other paths outlined above are viable too, but they’re based on images that preserve less information and thus require more manual work and figuring out to get the cave to its original or otherwise playable/beatable state.

The conversion tool autodetects and properly preserves the colors of the map, converting them from Krissz Engine 4-tone representation to a fully compatible 7-tone BDCFF definition. The map colors thus look exactly the same in Krissz Engine, BoulderCaves+, and GDash.

The cave size is also auto-detected and set in the BDCFF representation when the map is converted.

I'm hoping to be able to release this tool soon, hopefully before December or in early December (just need a bit more testing and fine-tuning on a large array of maps, which now I have a whole lot of thanks to Arno). Hopefully it will be of some use to someone, especially once BoulderCaves+ is also released publicly, and when some alternative Krissz Engine-compatible remakes are made (if this ever happens, of course).

-----

Some more time was spent today to improve the bundled cave editor. In particular, the following changes were made:

- The object under cursor is now shown in the title bar of the editor (might move later into a special status bar), along with its X and Y coordinates, direction (if applicable), and permeability (for slimes).
- There's now a button to show some basic cave statistics, such as the total diamond count, the count of various other objects on map, and the total slime count and impermeable slime count under current cave parameters.

Here's an example of the editor showing slime impermeability under cursor (in the title bar):


And this is how the cave stats button functions at the moment:


When it comes to the game engine, some subtle enhancements were made that make the game behave closer to the original BD and to Krissz Engine as well. In particular, the reveal demo when the cave starts is now properly animated (all the revealed objects are animated in sync), the timeout sound is now properly played during the final score count. These things might seem minor, but they are a part of the mechanical correctness of the engine as well. Subtle details that, in my opinion, either make or break the overall impression of how the game feels.

The conversion tool received its share of improvements too. In particular, there's now an experimental "GDash mode" which allows to convert the map, as much as possible (sans Light Boulder), to a format that would be immediately loadable in GDash, so that the necessary cave properties can be specified. While of limited use at the moment, this might be important later when and if GDash is also enhanced to support Krissz Engine features.

- Agetian

A lot of time was spent today improving the conversion tool algorithm. By now it can convert pretty much any map that I throw at it, regardless of the color set used (as long as there are at least 3 at at most 4 unique colors - 4 being the maximum that Krissz Engine supports). This tool is shaping up pretty nicely and will be ready for a public release soon. As of right now, I'm mostly working on adding options and making the tool easier to use for the end user.

I added an option that allows the tool to try detecting if the vertical and the horizontal borders should be marked as open. This is very experimental, and of course, it only decides by the presence of open spaces at the borders on two sides (opposite horizontal or opposite vertical borders), but sometimes it may help. Still, manual confirmation would be advised to confirm that the borders are actually marked as open and you can cross to the other side of the map.

When it comes to BoulderCaves+, some work was done to improve the game timings. Unfortunately, BoulderCaves requires quite a heavy overhaul in order to make it behave closer to Krissz Engine, but I'm slowly getting there, hehe Not a whole lot else to say for now, so have this screenshot of Trischi83's "Big Church" running in the updated engine, see if you can find some subtle changes in the interface that make the game somewhat closer to authentic

Old screenshot:


New screenshot (as of Nov 22, 2021):


When it comes to something that can't be seen on the screenshot, a lot of time and effort went into synchronizing Rockford's animation frames for blinking and tapping. The original BoulderCaves mostly had tapping right, but blinking was way out of whack, with Rockford blinking spastically on random frames and seemingly stopping the animation abruptly or restarting it from a random frame. The current solution is a bit hacky, but I'm hoping to improve it eventually. It's a minor thing, but it's sort of annoying to see Rockford go nuts and blink like crazy during the idle animation

- Agetian

Today I continued working on improving the mechanics of BoulderCaves+, making them closer to the original BD and to Krissz Engine mechanics. Several important bug fixes were made too, many of them related to scanning amoeba. Along those lines, the proper (frame-exact, I believe) implementation of the interaction between the amoeba update and the "Magic Wall Stops Amoeba" property was made, making, for example, this funny little cave (CSO 182 by Dustin) beatable in BoulderCaves+ in the intended way (using a cave scanning order trick and the Magic Wall Stops Amoeba feature which, I believe, was actually a bug in the original BD1):



Voodoo Rockford doesn't behave in Krissz Engine the same way it does in BoulderCaves (I believe it follows post-BD1 mechanics), so now in BoulderCaves+, when Krissz Engine compatibility mode is enabled, it behaves as it does in Krissz's, in particular, not catching diamonds and not blowing up if a boulder falls on it.

Several important changes were made in the editor too. For example, the objects now have their proper names and they're ordered the same in the tile selector as in Krissz Engine. Also, several icons were implemented from Krissz Engine that makes things look similar and also makes it easier to distinguish a slime from an amoeba when using a Krissz Engine cave palette.



- Agetian

Today I implemented some fixes and tweaks in the cave editor, but the most interesting and useful addition is the ability to show impermeable slime right on the cave map. It's done a little differently compared to Krissz Engine, but the principle is the same.



This makes the cave editor a lot more useful when dealing with caves that are built around the slime permeability feature.

- Agetian

The first post of this thread has been updated to match the current progress in this project. Quite a lot of changes were made in the last couple days, notably:

- The smaller caves are now properly centered, making them look more appealing and natural in the game. This supports all sorts of caves, including ultra-wide and ultra-tall caves. Here's an example of a small test cave being centered now (compare to the CSO 182 screenshot above where the map was drawn in the top left corner). Interestingly, this was meant to be a feature of the original BoulderCaves, but it was mostly unfinished and broken and needed a rewrite, especially in order to account for all the possible open border scenarios.



- KrisszConvert, a cave converter, received some important improvements that made it both more compatible and easier to use. This tool should be ready for a public release quite soon. More caves were converted to BoulderCaves+ engine, for example, here's Basti's "Pong" running in BoulderCaves+ (the cave is completable):



- Finally, there's now a simple window-based game launcher which only uses Tkinter as a dependency (which BoulderCaves(+) uses as well). It currently allows to choose a cave or a cave set to play and set a number of common game options:



Amusingly, while working on cave centering, I discovered what seems to be an issue with the wraparound/lineshift property implementations in the original BoulderCaves. At least I couldn't match the behavior to any existing engine, and the implementation would break on smaller maps, since it didn't account for the cave resize that reshaped the cave to fit the game window. I believe I fixed these implementations (they're not really relevant to Krissz Engine mode since it uses Open Horizontal/Vertical Border instead and doesn't use lineshift), but for other (e.g. GDash-compatible) caves it may be relevant. Currently my implementation seems to match what GDash (and probably CLCK) use by default.

- Agetian

Quite possibly the biggest news for today is that KrisszConvert, a tool to convert Krissz Engine cave images in PNG format into a BDCFF format compatible with the upcoming BoulderCaves+, has received its first public release. Thanks to Arno's contribution of a collection of cave pictures, I was able to quickly and significantly improve the quality of the converter which should currently be able to convert most caves thrown at it. You can find the released tool here. I sincerely hope that it will be used for preservation of caves from Krissz Engine and as a way to create playable versions of some of the best caves available in compatible clones, one of which is currently in development as outlined in this thread.

In other news, I spent some time testing the cave scanning order implementation. I tested many (though not all yet) of the dancing fly formations and they seem to behave the same as in Krissz Engine, including their edge behavior on open border maps, though this latter statement still requires more confirmation and testing. Especially concerning might be the case where the open border is complemented with the infinitely scrolling world, which BoulderCaves+ doesn't yet support (though this feature is eventually planned).

The editor received some behind-the-scenes improvements too, mostly optimizations. Cave stats and impermeable slime no longer cause a massive slowdown and lag on huge (e.g. 100x100) maps when mousing over the map or clicking the Cave Stats button, which now only takes a second or two instead of many minutes to complete on maps like that.

Amoeba received some more attention and testing, I ensured that the initially dormant amoeba behavior is consistent in BoulderCaves+ and in Krissz Engine.

As of right now, things are starting to shape up, and provided that there are no setbacks, BoulderCaves+ should receive its first public (beta) release closer to the end of the year, maybe as a Christmas gift For now, I would welcome any effort in converting and preserving the Krissz Engine caves in compatible extended BDCFF format using KrisszConvert, if anyone is willing and has time to test the tool and is willing to share their creations with the world in a portable, offline format.

Stay tuned for more progress!

- Agetian

Here's a little video demonstration of Dustin's CSO 143 being played in BoulderCaves+, demonstrating some Light Boulder action together with a small cave scanning order interaction on a map with open borders Also note the proper cave centering in the game window, as mentioned in the progress report above.
Video demonstration on Dropbox

The subtle bug with the Rockford facing in the wrong direction after the level ends is already fixed

- Agetian

A pretty bad bug was fixed in KrisszConvert today, and a new version was released in the relevant thread, please update your converter if you downloaded v1.0 yesterday.

Also, I spent some time optimizing the game draw routines - I started to wonder if Python is a good enough (fast enough) language for a BD engine, and guess what, I came to a conclusion that it is. After some optimizations, even very large maps (I tried up to 90 x 90 for now) animate the reveal demo smoothly at above 30 fps for me (and the cave itself plays smoothly even with a lot going on in it) even on standard Python 3 (without Pypy 3), and it's even faster when Pypy3 is involved.

Stay tuned for more progress

- Agetian

I tested BoulderCaves+ on a Raspberry Pi 4 today (overclocked to 2 GHz), and it ran very well. On most reasonably sized caves (40x22 and slightly bigger) it works without a hitch in 60 fps mode even without needing Pypy3. Bigger caves (80x80, 90x90) have noticeable slowdowns when running on stock Python 3, but perform smoothly (except for the somewhat lagging reveal demo at the beginning of the level) during the gameplay when run through Pypy3.

Fixed a few issues today, notably made Rockford Birth Time as close to frame-exact as possible when compared to Krissz Engine. For example, CSO Chessboard by Dustin now behaves the same when it comes to timing Rockford's birth versus the timing of the passing firefly. I might tweak the timing subsystem a little more later, but it starts to feel really close to what it should be at the moment.

- Agetian

So, the question that I asked myself today was: what kind of cave sizes can you play on BoulderCaves+? Originally in the code base of BoulderCaves, there was a restriction to have a minimum width/height of 4 and a maximum width/height of 100, though there were some issues with supporting certain cave sizes due to bugs both in the cave resizing algorithm (which made certain cave sizes crash) and in the border wraparound/lineshift algorithm that made it fail to work on caves that are smaller than the playfield size.

Over the course of the development, I changed the settings to match Krissz Engine (thus, now there's a minimum width and height of 2, and a maximum width and height of 100), and fixed the bugs that prevented certain cave sizes from working correctly or at all. After cave centering was implemented, BoulderCaves+ started to behave consistently with how Krissz Engine visualizes caves of different shapes and sizes.

As of right now, I tested BoulderCaves+ on all sorts of weirdly shaped caves - ultra small ones (like 6 x 3 or whatever), extra large ones (90 x 90, 100 x 100), ultra wide ones (e.g. 80 x 15), ultra tall ones (e.g. 10 x 92), and all sorts of in-betweens. Of course, the standard sizes of 40 x 22 and 20 x 11 were tested as well. It looks like at this moment, BoulderCaves+ can load pretty much any cave that Krissz Engine supports when it comes to its size.

I also ran some experiments in "unlimited" mode where I went beyond 100. Actually, BoulderCaves+ now works in a rather generic and size-agnostic manner when it comes to loading and visualizing caves (centering and all when needed), so it doesn't have any hard "technical" cave size restrictions that would prevent a cave like 120 x 120 or even 200 x 200 from working, but at those immense sizes, another question comes up: would your PC be able to take it when it comes to running a cave like that in a Python language environment? In most cases, I guess, the answer would be no, unless you're running Pypy3 and have a very powerful CPU. And if your CPU fails to catch up with the cave scan, all sorts of timing issues may start to pop up. Thus, 100 x 100 seems to be a reasonable upper limit for the time being.

As for the current upper limit of 100 x 100, I tested it on a variety of PCs and even on a Raspberry Pi 4. On modern machines, it's possible to run a moderately "busy" 100 x 100 map without worrying about running under Pypy3, especially if you don't mind seeing a possible slight "lag" during the reveal demo. On weaker PCs such as the Pi 4, a Pypy3 environment is pretty much required for maps like 90x90 or 100x100 to run smoothly, and certain optimizations may be necessary in the code in order to make them run better on machines like that (I'm still working on it).

In other news, I'm continuing to work on improving the mechanical compatibility of BoulderCaves+ with Krissz Engine. Interestingly, at the moment, most cave scanning order (CSO) interactions and subtle timings seem to work as needed, but certain corner cases are "unexpected" in the original Boulder Caves engine and lead to a crash. For example, CSO 77 by Dustin, which relies on entering the outbox right before a Voodoo Rockford blows up, taking Rockford and the Outbox with it, was completable but the game crashed, since it did not expect Rockford to "disappear" from the playfield when the game was already in the "victory" state. I fixed this issue, and now CSO 77 can be completed without any issues.

Sooo, for now, here are some screenshots of various maps I converted and tested recently as I experimented with cave sizes and CSO.


CSO 77 by Dustin, demonstrating a weird interaction where Rockford triggers the outbox right before blowing up to a Firefly scan which blows up a Voodoo Rockford.


"Almost Impermeable" by Arno. No, I have no idea how to test whether this map can be completed, lol - I can't even beat it once on actual Krissz Engine. All I can say for now is that it behaves very similar to how it does on Krissz Engine, with different diamonds falling at different time and with the leftmost one falling through the magic walls depending probably on which slimes get scanned before the first slime is blown up. However, I'm not so good at BD to be able to trigger this in a frame-exact manner so that the leftmost diamond falls last ^^;

- Agetian

The biggest improvement today is the implementation of Full Screen mode for Boulder Caves+, which runs quite smoothly and looks nice in 1920x1080.

The integrated cave editor (Construction Kit) received its share of improvements as well. Now there's a better way to specify the direction of flies (a radio button - based selection with arrows). The editor can be started directly from the Game Launcher now, and when it does, it runs in Krissz Engine-compatible mode in case Krissz Engine game style is selected in the Launcher, automatically suggesting the relevant defaults and color palette.

The implementation of Full Screen prompted some changes in KrisszConvert (mostly minor), in particular, the border color in the converted caves is now set to #000000 (Black) to offer consistent experience with Krissz Engine, especially when in full screen mode. A new version has been released with these changes in the Tools forum.

- Agetian

Several interesting improvements in game mechanics were made in BoulderCaves+ today. For example, Dustin's CSO 199 wasn't completable because the three boulders on top of each other interacted in a strange way, with the top one jumping off to the left off the second one. After a lot of searching and debugging, I narrowed it down to a subtle bug in the original BoulderCaves implementation of rolling check which allowed objects to roll off other objects regardless of whether they were stationary or falling. Now that this is fixed, CSO 199 is completable in BoulderCaves+.

Other things were mostly "flavor", things like the Magic Wall making a diamond sound as it should per the BDCFF specs instead of no sound at all that it used to (not) make in BoulderCaves.

Several more maps were converted using KrisszConvert, by now I'm not quite satisfied with how the converter works and I no longer encounter any issues that I feel would need addressing.

- Agetian

Alrighty, in the last couple days I worked primarily on polishing and fixing game mechanics in BoulderCaves+. While doing so, I found something in the original BoulderCaves code base that I believe is not a very good thing to do if you're coding a Boulder Dash clone/remake with the aim for mechanical correctness, so I would like to share this information with you.

It started with trying to figure out why Dustin's CSO 194 did not work on BoulderCaves as intended. The thing was - Rockford seemed to always be one frame late to the exit, so I suspected a CSO-related issue somewhere. The thing is, after spending nearly a day pondering over things and looking through the code, I found nothing at all wrong with the cave scanning order or the mechanics of processing individual elements in order, as such. That puzzled me until I realized that there was something in BoulderCaves that allowed to completely break the cave scanning order for certain things - animation callbacks.

You see, there were three things in the game - standard explosion, diamond birth (e.g. a butterfly explosion), and Rockford birth (at the beginning of the game) - tied not to the cave scan directly, but to what is called an "animation callback". Basically, when the animation of the explosion or the birth is finished, the game would call an update routine that changes the effect into the final object (an empty, a diamond, or Rockford). The major problem with that was that (a) in the original BoulderCaves, the time spent animating these objects was rather arbitrary, and did not even necessarily land on a cave scan frame end. But even if that was fixed (the first thing I did was synchronizing those animations to frames), the update call happened one frame too early, since the empty cell (or Rockford, or Diamond) was generated on the same frame when the last animation frame was played, not next frame as it should be (and as confirmed by caves like CSO 40). There was also problem (b) - the fact that the exact timing of executing the update depended on the animation system, not on the cave scanning order! Thus, if, for example, there was a lag spike (which actually could be the case with a Python game on low-end hardware), that lag spike would throw off the animation timing, and that would actually break the timing for per-frame updates of explosions and even for Rockford birth. I was actually puzzled once when I was testing optimizations on Raspberry Pi and saw that if the reveal demo of the cave was slow or laggy, then Rockford would be born a few frames too late. I was wondering how that was possible, and I found the answer in the form of animation callbacks.

So, I removed the animation callbacks completely and converted all three effects (explosion, diamond birth, Rockford birth) to actual game objects processed in cave scanning order, as I believe they should be. Not only did this fix the issue with Rockford birth time being off sometimes, it also fixed the issue with CSO 194 explosions, and it allowed both CSO 194 and CSO 40 to be fully completable with the intended solutions.

I also spent some time working on polishing the frame-exact implementations of Rockford birth and the "Game Speed" feature as such, measuring what should happen frame by frame in the reference implementation (Krissz Engine) and comparing it to the behavior of BoulderCaves+. As a result of this work, the feel of the game when it comes to speed and timing of the cave start now is about as close to the original implementation as I can make it thus far, with no noticeable differences that I can tell even on complex maps (e.g. the timing of Rockford birth vs. the firefly passing on CSO 100 was confirmed to now be what it should be, and yes, it's no longer thrown off even in the event of reveal demo animation lags).

I spent some time pondering over the CSO 206 effect with the amoeba conversion using a magic wall. I tried to follow Dustin's explanation of what happens and I believe I managed to replicate the effect and the order of actions specified in the explanation. It was a fun challenge. I still need to confirm that CSO 206 can now be completed on BoulderCaves+ though.

As for KrisszConvert, I believe it's now production ready - I converted a good number of maps of all sorts of color schemes and sizes by now and I haven't come across any more issues that would need fixing. At least so far, fingers crossed.

Stay tuned for more updates, as usual

- Agetian