How to handle extra functionality?

[tehKaiN]

I've adapted Jeroen Knoester's audio mixer for ACE's use as a standalone manager (currently available on Aminer repo on separate branch), but I have some doubts if I should incorporate it into ACE:

• it's written in asm (contradicts C in ACE's name ;) )
• wrapper is not 100% complete and some liberal choices were made in its configuration/implementation

on the other hand, there are counterarguments:

• easier to discover by other ppl when it's part of main repo
• ACE community is not that big and most probably main repo won't be overbloated with contributed components (kinda wishful thinking)
• I'll probably use it in all next games from now on, so that means 2 git submodules instead of 1
• could be made more generic as time progresses

on even other hand, there are some features proposed by other ppl (Kwahu's voxel renderer, generic entity-component system) which I'm not sure if should be added because:

• they're quite optional
• target very specific kinds of games
• come with specific set of limitations and/or cost

For the same reason I'm holding back from adding my bob system - my first thought was to release few titles using it to be sure that it fits many usage scenarios, but perhaps that too should be separate package.

Also, I'm afraid that as those extra packages get incorporated, incompatibilities between them may arise, forcing me to make sure that everything works in any configuration, perhaps sacrificing speed for compatibility.

What do you, as ACE users, think of it? What rules should be used to determine if feature should be added to ACE? Should ACE itself be tiny bare-bones framework/environment or a Swiss army knife?

[kwahu]

when I work with something new and it's included as a part of repo with a working example than it's much easier for me to start experimenting with it and get familiar looking at separate repos is always a hussle for me, and following instructions on combining things is not easy for me as I don't program on a daily basis anymore.

I prefer if it's all combined even if there are LIMITATIONS. If I need something for my game and I have a working example of something that is not yet finished it's still a big help and a motivation to help the author with further work.

It's a psyhical barrier for me to download and try a separate repo that is not yet finished, if you know what I mean. I prefer to help somebody than do develop my own solution from scratch if I need it for my current project. Having all that in one place with a documented limitations and cautions is my personal preference

[timfel]

I like the idea of having more things available. But it's a maintenance burden to shoulder. Regarding the performance cost of abstraction, the way I see that since ACE breaks compatibility once in a while anyway, for a specific game I would just modify the ACE code for that game if it needs the extra performance. Sure, it makes the ACE in the game diverge from mainline, but after some development on ACE master, it won't be compatible anymore either.

[tehKaiN]

related to #74

[approxit]

If we zoom out enough we can see following things: discoverability, maintenance and compatibility. I think that ideal solution would be to keep great discoverability, keep the lowest ACE maintenance and compatibility moved from the shoulders of ACE.

In discoverability/maintenance we have de-facto following choices:

1. Simplest option would be to just develop everything in ACE repo - which have a lot of drawbacks, too many to even have a need to write them down here.
2. Close enough option would be to keep all extensions (or whichever term would be officially used) as a submodules in ACE repo - great discoverability but it would require to maintenance creation/deletion/updates(?) at ACE side, which is not so optimal
3. Next option would be to just keep extensions outside of ACE, but somehow maintain a curated list of them - which seems to be fine, but it will still require some manual work
4. Last option here would be to have somewhat automated list of ACE extensions - in this case GitHub's tags would be a great solution.

In compatibility I see few remarks:

• As ACE games uses submodules (for ACE itself) anyways, adding another submodules would not be a big deal.
• As ACE games uses kinda similar code-layout pattern (something into direction of convention over [manual] configuration), ACE extensions could benefit from that and use well defined code layout / naming conventions.
• At some point it would be required to keep track of breaking changes via semantic versioning and at least comment on breaking changes in merged PRs.

From my side, I'm in favor of option 4. Proper instructions for extension developers would keep extensions as easy as single git submodule add, keeping automated extensions list based on GitHub's tags and have it well displayed in ACE docs, would be a sweet spot for all mentioned cases and for all three parties: ACE, extension developers, extension users.

[tehKaiN]

Another idea. I've thought about whether some of ACE parts shouldn't be considered extensions.

• most current ACE stuff can be safely considered core:
  • all current managers, perhaps except:
  • ptplayer, because there are other players, but who doesn't need music?
  • old audio manager, because it doesn't work properly and ptplayer is superior for sfx playback
  • all the utils, except:
  • bmframe, which I haven't used for a while, but it's small enough and easy to maintain
  • perhaps chunky, because not all games need chunky/planar conversion, on the other hand it's one of core concepts on Amiga
• Libfixmath can be considered an optional part because it's not written by ACE's authors and not all games require it, but some other ACE parts depend on it (chunkyRotate uses sin/cos values in fix16 format). Also, I think it's good to have unified/recommended fixmath library for Amiga development, but that's personal taste.

so to determine which parts are core and which aren't I've answered following questions:

• are there significantly different solutions to same problem? If so, perhaps ACE should come bundled with most common/generic one.
• are other solutions better and ACE's development time should focus on them instead?
• is given functionality needed or nice to have for most of games?
• is it used often in tandem with ACE? (rephrased point above)
• is it small/simple enough to not require that much maintenance?
• is the functionality related to a core Amiga concept?
• is it entirely, or its ACE interface, written by core ACE team or frequent contributors?
• is it a building block or dependency for other parts of code? How much coupling there is between this part and rest of ACE code?

Now if I try to answer those questions for ACE extensions mentioned earlier:

• audio mixer:
  • more elaborate mixing libraries could be developed, but they would come with significantly bigger performance cost, and most games will be cool with feature set of this mixer
  • I think it's the best audio mixer for games currently available, performance- and feature-wise
  • not every game needs it, but fast and basing mixing solution opens up opportunity to raise bar for all ACE productions
  • the functionality is a thin wrapper for 3rd party library, so there's little maintenance cost of its code. It uses already established ACE mechanisms for interrupt/dma management. It needed some extra functionality from audio converter tool, though.
  • mixer interface for ACE is written by me
  • no other ACE code depends on it
• bob manager:
  • could be done differently at least in 2 ways: interrupt-driven blitter queue, copper blits
  • each solution has its own pros and cons, unfortunately, but this one is most generic one and can be integrated into any codebase.
  • bobs are 99% required part of the games
  • it's not as tiny piece of code as audio mixer, it's contained in single .c/.h file, and it's code of significant complexity (somewhere between copper and tilebuffer manager)
  • bobs are core Amiga graphics concept
  • written by me
  • can become a building block for more complex stuff, but it's usually used directly

For other stuff, I'll let others do the self-assessment of their code if that's the approach we choose to follow. Extra questions which were answered in assessments above:

• does it allow to make significantly better games at reasonable performance cost?
• is most of the code first-party?
• does it require some extra parts of ACE functionality/tooling for its use?

Could such assesments be helpful on determining if those things are core or should be kept separately as extensions? Should we go through such checklist for each pull request with new code?

[tehKaiN]

Bump. Personally I think refining such self-assessments is the way to go to determine whether stuff goes into main repo, but I would like to hear some more opinions if the idea is solid.

[Vairn]

Have you thought about having a contribution, contrib, section where it has these not core but user contributions? Then it is still optional but supported by ACE?

This doesn't work for my AGA stuff since it deals with to many internal systems. But it would be an interesting idea.

⁣Get BlueMail for Android ​

On 2 May 2023, 6:24 pm, at 6:24 pm, KaiN @.***> wrote:

Bump. Personally I think refining such self-assessments is the way to go to determine whether stuff goes into main repo, but I would like to hear some more opinions if the idea is solid.

-- Reply to this email directly or view it on GitHub: https://github.com/AmigaPorts/ACE/issues/189#issuecomment-1531073601 You are receiving this because you are subscribed to this thread.

Message ID: @.***>

[tehKaiN]

What I'm afraid of with having a contrib folder inside main repo, is that I and other maintainers will have to support that code and make sure that it builds and works with every PR and internal ACE changes. This may be fine at first when there's not a lot of it but then it could pile up to quite a burden and may even require total rewrite of one or ten contrib modules when refactoring parts of ACE. If we assume that the person who added something to contrib folder must keep it up to date with separate PRs, I fear that in time some things will rot away and repo will be cluttered with broken code. What I'd like to do is to keep the contents of repo neat and tidy, moving the effort of maintaining "optional enough" stuff to other people.

If we go the way of contrib stuff in separate repo, then yeah, some unified structure would have to be conceived, so that one can call contrib stuff with #include <ace/contrib/foo.h> or something like that.

[tehKaiN]

Time to make some decisions.

I think we could give the whole thing the benefit of the doubt and see what happens when we accept all contributions unless they don't fit into core engine significantly.

What does significantly mean in this context? Dunno really. I'll try to do some kind of contribution guidelines based on discussion above and self-assessment PR template. Regarding my code, I'll create PRs with audio mixing and bob systems soon and see if anyone opposes.