Remove games/large examples to their own repositories

[Gadgetoid]

The following should move into their own GitHub repositories under the 32blit umbrella:

• [ ] Voxel
• [ ] Rainbow Ascent
• [ ] Ray Caster
• [ ] Geometry
• Probably some others?

Anywhere this leaves a gap in coverage, a basic test example should be added.

We can probably also still build these examples and pull them in to the release .zip file, or append them as a "games.zip".

Or... y'know... direct people to Blithub!

[Daft-Freak]

Flight is an "interesting" one, it's the only mode7 example, but it also uses the Map class that nothing else does. (and has some serious issues with build times in debug builds). I think I had some patches to use the same map stuff as everything else somewhere...

I guess racer would be on this list if it existed and shmup if there was a game in there...

[Gadgetoid]

Obvious garbage like racer and shmup could probably be summarily deleted. It's not like the history isn't there if anyone wants to revive them to a new project... and it's not like either really has any useful content.

Albeit shmup is a rather nice palette cycling demo under all the guff :laughing:

[Daft-Freak]

Deleting things is fun: https://github.com/Daft-Freak/32blit-beta/commit/4f4f347f9e4d427361028fc7c357f00aab73e146. (I guess if you want a "racer", there are at least 3 games on BlitHub.)

[Daft-Freak]

What if we did this: https://github.com/Daft-Freak/32blit-examples (stealing the idea from pico-sdk/examples)

... then made the SDK's actions pull that so we're build testing the same things. (and update the docs)

[ahnlak]

Looks awesome; wondering if it makes sense to divide it into "examples" (or specific tech / API / technique) and "games" (which are more complete and not showcasing anything specific)

[Daft-Freak]

Hmm, probably a good idea... Shouldn't be hard to recoganise things, that was just a quick ../git-filter-repo --path examples --path assets and then throwing in some of the boilerplate so that it built.

[Gadgetoid]

What if we did this

That's a great idea, keeps the SDK lean and to the point without forgoing our "testing"

Does this mean we'll end up with a 32blit-extras? :laughing:

[Daft-Freak]

Expect a PR with a lot of deletions then :laughing:

... anyone feel like writing the README for 32blit-examples?

Does this mean we'll end up with a 32blit-extras? laughing

I think that's called Daft-Freak/32blit-beta.

[Daft-Freak]

So this completely breaks the .sln... my preferred solution (hah) is to delete it... any other suggestions? (I currently don't have a full VS install)

Other smaller problems:

• Should the SDK releases include the examples or should there be examples releases at the same time? (I've currently got them in the artifacts, but we would get two separate release packages)
• The assets ended up in the examples repo (some are used there), this may not be a problem. (Unless there are things that expect them to be in the SDK?)
• firmware-update still doesn't have a "magic" splash image! Okay, that isn't really a problem...
• Still need to go through all the documentation

https://github.com/Daft-Freak/32blit-beta/tree/split-examples

[Gadgetoid]

Actually maintaining the .sln is an eldritch horror, and I also lack a VS install. It has some utility to windows-based devs, though, easy access to profiling, debugging at least on a host PC. I'm kind of remiss to remove it altogether, but realise I'd be volunteering to fix it if I vote stay.

I'm going to take it @ahnlak votes "delete it" :laughing: https://github.com/32blit/32blit-sdk/commit/4156d4274dbfa18f958577f35f266c798e902c71

It doesn't really have many die-hard fans...

1. For simplicity's sake I think the SDK releases should include device firmwares only, most of the examples exist more or less purely as a jumping off point for beginners and those that don't should be distributed via Blithub.
2. As long as we point people in the right direction, I don't think anyone's going to care
3. A magic whatnow?
4. :sob: probably wouldn't hurt to kick the tyres on this anyway, mumble mumble it should also probably be rendered to HTML and added to 32blit-website mumble mumble

[ahnlak]

I have no memory of that commit, but certainly echo the sentiment :rofl:

Given that VS plays nicely(?) with CMake these days, I'm inclined to say kill it with fire.

[Daft-Freak]

I'm pretty sure at least debugging works with the "Open folder" thing. There was never really a way to use it with the boilerplate anyway.

In the 70-ish repos I have for the bot, there are 5 with .vcxproj files (from the same user). So I don't think it was very widely used.

1. I guess this means not releasing anything for !STM32 (for now at least)

...

3. https://github.com/32blit/32blit-sdk/pull/468#issuecomment-747736444 (Just me remembering mostly-useless info)

[Gadgetoid]

I looked into how many examples I need to write pithy descriptions of to make an example readme and died inside, if removing VS saves effort (it's probably going to make more work ugh) then I concur.

I think Geometry, Ray Caster and Rainbow Ascent probably:

1. All need to be in their own individual repos with,
2. Lots of comments and hints about what they're doing and why and,
3. Some good accompanying documentation and resource links.

That, unfortunately, is my problem I think...

As for PicoSystem Hardware test and 32blit Hardware test... not really sure about those.

Sheesh I wonder why I never came back with some cover art. That wasn't even the year I got totally absorbed into writing Sprite Editor.

[ali1234]

Hardware test is really useful for bringing up new (or very old) hardware. It would be even more useful if there was a way to build it for internal flash without having to hack around the build files. Can this be done in an external repo? If not then I think it should stay in main. Maybe some of the functionality could even be merged into the firmware itself.

[ahnlak]

I would offer to help with the comments / docs on those three but... I don't know how any of them work :rofl:

I do keep wondering if there's a handful of simple, classic games "someone" could build in a fully commented, documented, tutorial-ified form (but that may be a 'future' job)

[Daft-Freak]

I've deleted vs in the branch to fix the build fail for now. Building the examples is quite a large chunk of the build docs, ugh. (Writing is definitely not my thing...)

Yeah, hardware-test is quite useful, I use it a lot for pico testing. Don't think blit_executable_int_flash works outside the SDK though. :thinking:

Merging some of it into the firmware doesn't help me much due to how uh, device-specific the firmware is. (Maybe this will improve as part of my attempt to get full functionality on [some other device]...). Not saying that a "test mode" in the firmware isn't a good idea though.

[Gadgetoid]

I started putting together an examples README, but I'm being pulled in all directions at the moment, so bear with me.

I do wonder if the docs need a thorough overhaul and just to live in 32blit-docs. They have grown a little organically and having them in a separate repo would make it easier to tool up for publishing them as HTML, and let us amend the docs without triggering CI on the SDK :laughing:

Do worry about change for change's sake, though, versus doing stuff to actively position this project for the new few years of development.

[merwok]

It is nice to have docs located with the code.

To avoid unnecessary CI, you can always detect which files are changed by a PR and only build docs. Example to prevent builds: https://github.com/python/cpython/blob/main/.github/workflows/build.yml#L60 Example to run doc jobs: https://github.com/python/cpython/blob/main/.github/workflows/doc.yml#L23

[Gadgetoid]

Wow, TIL that paths-ignore is actually kinda self defeating :grimacing: But noted, thank you!

[Daft-Freak]

Maybe we need another issue for sorting out the docs :thinking:

[Daft-Freak]

Hah, I've locked myself out of the settings for 32blit-examples :facepalm:

[Gadgetoid]

Fixed, I think!

[Daft-Freak]

If we keep the hardware-tests here, where should they go? ("examples" doesn't really fit any more, and... naming things is hard).

Also thinking of moving firmware/firmware-update under 32blit-stm32, as they're really tied to that platform... but that's another issue.

[ahnlak]

"utilities", maybe? (which might be a good home for @Gadgetoid's sprite editor, too...)

[Daft-Freak]

Went with that for now. The sprite editor is quite big so maybe not...

[Gadgetoid]

"quite big" is a polite way to put that sprawling mess :laughing: