Proposal: File organization and class exposure

[renancaraujo]

This is a proposal to organize the files inside the package following the dart's Package layout conventions.

Current way

Currently out internal directory organization is like:

lib/
├── assets/
|   ├── ...
├── components/
│   ├── ...
│   ├── joystick/
│   │   └── ...
│   ├── mixins/
│   │   └── ...
│   ├── ...
│   ├── <lots of components>
│   └── ...
├── effects/
│   └── ...
├── extensions/
│   └── ...
├── game/
│   └── ...
├── layers/
│   └── ...
├── particles/
│   ├── ...
│   ├── <lots of particles>
│   └── ...
└── widgets/
│    └── ...
└── ...

• This may be a problem when we need to control what to expose as API. We can have ambiguity or we can end up exposing stuff that shouldn't be used directly.

Examples:

• The flame.dart file exposes elements of the Util class located in the util file. This brings ambiguity in the API since the util functions can be used via importing either flame/flame.dart or flame/util.dart.
• GameRenderBox should not be part of the public api, but nothing stops the user from importing flame/game/game_render_box.dart

The idea

By following the convention, the file organization can become more like:

lib/
├── src/
|   └── ... all the implementation files
└── ... files that expose API sections, like for example a `effects.dart` or a `gestures.dart`

Top-level files can be like the ones in the Flutters package, only exposing what should be exposed. These export files can be separated by features, sections. They can be faced as "sub" packages
Advantages of adopting the convention:

• More simple and concise imports:

Things like:

import 'package:flame/components/component.dart';
import 'package:flame/particles/circle_particle.dart';
import 'package:flame/particles/composed_particle.dart';
import 'package:flame/particles/curved_particle.dart';

can become like:

import 'package:flame/components.dart';
import 'package:flame/particles.dart';

• Possibility to hide implementation files.

Not all files in the package contain elements that should be exposed as a package API. Files under src/ are warned to not be imported in dart compatible editors.

[luanpotter]

I can see some very specific use case for people wanting to use game_render_box directly. That is not common, and we should not encourage it, but I didn't want to make it forbidden. if it's allowed with a warning, I think it's a good middle term. They can use and send a PR to fix out exposed APIs so that they suit their needs.

[renancaraujo]

I can see some very specific use case

The fork button is there for those cases.

[renancaraujo]

Locking since it was fixed on #621