kgress 0.0.12

  • Readme
  • Changelog
  • Installing
  • 25

Introduction #

Some code to help me make an RPG like game in a phone app. This project is built on top of the Flame Flutter Game engine.


This project is still very much under development. Documentation below is not yet fully completed!

Getting Started #

Examples #

You can run the examle game by changing main.dart to the following:

import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import 'package:kgress/example/world/example_game_world.dart';
import 'package:kgress/game/world/container/cupertino_game_container_app.dart';

//  Run the example game

Game Tools #

KGRESS comes with tooling to allow you to preview areas in your game. You can switch to using these tools by updating the main.dart to the following:

import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import 'package:kgress/game/tools/cupertino_game_tool.dart';

//  Run the game editor tool
GameCartridge exampleGame = GameCartridge(
  areas: List.from([
  elementDrawerRepo: ExampleElementDrawerRepository()

Elements #

Elements are characters/things on the screen. They are everything from NPCs to your character to tiles on the floor.

Definining an Element Kind #

Element kinds come in various flavours. For example, this defines a floor tile:

ElementKind decorativeTile = StationaryObjectKind(name: "Fancy Floor Tile", stationaryImage: greenGrayTile);

Adding Images #

In order to create an element kind you need to specify an image set that will be used for rendering it. The simplest kind of image set is the SingleImage. In the case of defining a couple of tile images you would do this:

SingleImage greenTile = SingleImage("green_tile.png");
SingleImage greenGrayTile = SingleImage("green_gray_tile.png");

Keep in mind that you need to make sure all of your images are available in a folder called 'images' under the assets folder of your project.

Adding Animations for Movement #

Images for a character that can walk around on the screen require specific image sets for each state the character can be in.

For example, to create the animations for a player character you might do the following:

class PlayerCharacterSets {
  static final SpriteSheetRowSequence imgSetGoingUp = SpriteSheetRowSequence.fromStart('player_character.png', 64.0, 64.0, 8, 9);
  static final SpriteSheetRowSequence imgSetGoingDown = SpriteSheetRowSequence.fromStart('player_character.png', 64.0, 64.0, 10, 9);
  static final SpriteSheetRowSequence imgSetGoingLeft = SpriteSheetRowSequence.fromStart('player_character.png', 64.0, 64.0, 9, 9);
  static final SpriteSheetRowSequence imgSetGoingRight = SpriteSheetRowSequence.fromStart('player_character.png', 64.0, 64.0, 11, 9);
  static final SpriteSheetRowSequence imgSetStationary = SpriteSheetRowSequence.fromStart('player_character.png', 64.0, 64.0, 1, 7);

Placing the image sets inside a class like this is not required though it does help to more cleanly organize your image sets.

To use the images in creating the player character you can define an element kind as follows:

ElementKind playerCharacter = StatefulObjectKind(elementTypes.playerCharacter, directional, statesToImageSets: {
  states.stationary: PlayerCharacterSets.imgSetStationary,
  states.movingUp: PlayerCharacterSets.imgSetGoingUp,
  states.movingDown: PlayerCharacterSets.imgSetGoingDown,
  states.movingLeft: PlayerCharacterSets.imgSetGoingLeft,
  states.movingRight: PlayerCharacterSets.imgSetGoingRight,
}, name: "Player Character");

Adding an Element #

You add an element to an area in the game by using its element kind:

  Area currentArea = Area(10, "Test Area");

  AreaForEdit editor = AreaForEdit(currentArea);
  editor.fill(floorTile, layer: 0);

  editor.add(decorativeTile, 0, 0);

The code above adds your new "decorative tile" to the top corner of the area.

Adding movement and actions #

You can specify some actions for an element you want to add to a scene by using a variation on the code for adding an element.

  Area currentArea = Area(10, "Test Area");

  AreaForEdit editor = AreaForEdit(currentArea);
  editor.add(nonPlayerCharacter, 10, 10, actionSetActions: backAndForthActions);

The code above adds an element of kind "nonPlayerCharacter" to the area and gives it actions to execute.

Architecture #

Overarching Architecture #

Gameworld #

Elements #

Elements (things on the screen in an area of the game) have element kinds, which fall under over-arching element types.

Imagesets #

Imagesets provide canned frame sets for drawing elements on the screen. Elements can thus be added to a scene without your needing to worry about how they will be rendered.

Game Cartridges #

Relationship between the Game Cartridge and Components in a Game

Actions #

Tooling #

0.0.1 #

Initial published version

0.0.10 #

  • Update exposed libraries to include element kinds
  • Expose image sets

0.0.11 #

  • Improve documentation for image sets and element kinds

0.0.12 #

  • Code cleanup - remove redundant image loading
  • Fix bug with crashes when trying to use controls just after game starts

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:

  kgress: ^0.0.12

2. Install it

You can install packages from the command line:

with Flutter:

$ flutter pub get

Alternatively, your editor might support flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:kgress/kgress.dart';
Describes how popular the package is relative to other packages. [more]
Code health derived from static analysis. [more]
Reflects how tidy and up-to-date the package is. [more]
Weighted score of the above. [more]
Learn more about scoring.

We analyzed this package on Jan 16, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.7.0
  • pana: 0.13.4
  • Flutter: 1.12.13+hotfix.5

Health issues and suggestions

Fix lib/game/components/buttons/ControlArea.dart. (-21.75 points)

Analysis of lib/game/components/buttons/ControlArea.dart reported 4 warnings, 8 hints, including:

line 55 col 24: The parameter 'onPressed' is required. .

line 66 col 32: The parameter 'onPressed' is required. .

line 73 col 32: The parameter 'onPressed' is required. .

line 84 col 28: The parameter 'onPressed' is required. .

line 53 col 29: Name non-constant identifiers using lowerCamelCase.

Fix lib/game/tools/cupertino_element_kinds_tool.dart. (-11.10 points)

Analysis of lib/game/tools/cupertino_element_kinds_tool.dart reported 2 warnings, 3 hints:

line 129 col 30: The parameter 'onSelectedItemChanged' is required. .

line 179 col 30: The parameter 'onSelectedItemChanged' is required. .

line 15 col 7: This class (or a class which this class inherits from) is marked as '@immutable', but one or more of its instance fields are not final: CupertinoElementKindsToolApp._elementKindsToolsPresenterProvider, CupertinoElementKindsToolApp._cartridge, CupertinoElementKindsToolApp._elementKinds

line 43 col 7: This class (or a class which this class inherits from) is marked as '@immutable', but one or more of its instance fields are not final: CupertinoElementKindsTool._elementKindsToolsPresenterProvider, CupertinoElementKindsTool._cartridge, CupertinoElementKindsTool._elementKinds

line 68 col 27: The value of the field '_elementDrawerRepository' isn't used.

Fix lib/game/tools/cupertino_game_tool.dart. (-11.10 points)

Analysis of lib/game/tools/cupertino_game_tool.dart reported 2 warnings, 3 hints:

line 125 col 30: The parameter 'onSelectedItemChanged' is required. .

line 176 col 30: The parameter 'onSelectedItemChanged' is required. .

line 16 col 7: This class (or a class which this class inherits from) is marked as '@immutable', but one or more of its instance fields are not final:, CupertinoGameToolsApp._elementKinds

line 48 col 7: This class (or a class which this class inherits from) is marked as '@immutable', but one or more of its instance fields are not final: CupertinoGameToolingScaffold._presenter, CupertinoGameToolingScaffold._gameWorld,, CupertinoGameToolingScaffold.kinds

line 120 col 8: The method doesn't override an inherited method.

Fix additional 54 files with analysis or formatting issues. (-7.99 points)

Additional issues in the following files:

  • lib/game/controller/element_controllers.dart (3 hints)
  • lib/game/tools/elementKinds/ElementKindsToolElementController.dart (2 hints)
  • lib/example/drawers/ExampleElementDrawerRepository.dart (1 hint)
  • lib/example/world/example_game.dart (1 hint)
  • lib/game/actions/actions_interactor.dart (1 hint)
  • lib/game/actions/builtin/element_actions/action_move.dart (1 hint)
  • lib/game/components/Direction.dart (1 hint)
  • lib/game/components/speech/SpeechArea.dart (1 hint)
  • lib/game/controller/Proximities.dart (1 hint)
  • lib/game/controller/element_controllers_repository_default.dart (1 hint)
  • lib/game/elements/element_kinds.dart (1 hint)
  • lib/game/world/container/cupertino_game_container_app.dart (1 hint)
  • lib/game/world/game_world.dart (1 hint)
  • lib/example/example_areas.dart (Run flutter format to format lib/example/example_areas.dart.)
  • lib/example/example_game.dart (Run flutter format to format lib/example/example_game.dart.)
  • lib/example/images/example_image_sets.dart (Run flutter format to format lib/example/images/example_image_sets.dart.)
  • lib/example/kinds/example_kinds.dart (Run flutter format to format lib/example/kinds/example_kinds.dart.)
  • lib/game/GameWorldBridge.dart (Run flutter format to format lib/game/GameWorldBridge.dart.)
  • lib/game/MainGame.dart (Run flutter format to format lib/game/MainGame.dart.)
  • lib/game/actions/action.dart (Run flutter format to format lib/game/actions/action.dart.)
  • lib/game/actions/action_set.dart (Run flutter format to format lib/game/actions/action_set.dart.)
  • lib/game/actions/builtin/Await.dart (Run flutter format to format lib/game/actions/builtin/Await.dart.)
  • lib/game/actions/builtin/control_actions.dart (Run flutter format to format lib/game/actions/builtin/control_actions.dart.)
  • lib/game/actions/builtin/element_actions/element_action.dart (Run flutter format to format lib/game/actions/builtin/element_actions/element_action.dart.)
  • lib/game/actions/builtin/events.dart (Run flutter format to format lib/game/actions/builtin/events.dart.)
  • lib/game/actions/builtin/mixins.dart (Run flutter format to format lib/game/actions/builtin/mixins.dart.)
  • lib/game/actions/element_action_set.dart (Run flutter format to format lib/game/actions/element_action_set.dart.)
  • lib/game/areas/model/Area.dart (Run flutter format to format lib/game/areas/model/Area.dart.)
  • lib/game/areas/model/AreaBuilder.dart (Run flutter format to format lib/game/areas/model/AreaBuilder.dart.)
  • lib/game/cartridge/GameCartridge.dart (Run flutter format to format lib/game/cartridge/GameCartridge.dart.)
  • lib/game/components/animation/CharacterAnimations.dart (Run flutter format to format lib/game/components/animation/CharacterAnimations.dart.)
  • lib/game/components/buttons/ControlsDelegate.dart (Run flutter format to format lib/game/components/buttons/ControlsDelegate.dart.)
  • lib/game/components/images/ImageRepository.dart (Run flutter format to format lib/game/components/images/ImageRepository.dart.)
  • lib/game/controller/area_context.dart (Run flutter format to format lib/game/controller/area_context.dart.)
  • lib/game/controller/area_controller.dart (Run flutter format to format lib/game/controller/area_controller.dart.)
  • lib/game/elements/element.dart (Run flutter format to format lib/game/elements/element.dart.)
  • lib/game/elements/element_interactors.dart (Run flutter format to format lib/game/elements/element_interactors.dart.)
  • lib/game/elements/element_types.dart (Run flutter format to format lib/game/elements/element_types.dart.)
  • lib/game/imagesets/element_drawers.dart (Run flutter format to format lib/game/imagesets/element_drawers.dart.)
  • lib/game/imagesets/image_set.dart (Run flutter format to format lib/game/imagesets/image_set.dart.)
  • lib/game/states/state_spaces.dart (Run flutter format to format lib/game/states/state_spaces.dart.)
  • lib/game/states/states.dart (Run flutter format to format lib/game/states/states.dart.)
  • lib/game/tools/GameToolsPresenter.dart (Run flutter format to format lib/game/tools/GameToolsPresenter.dart.)
  • lib/game/tools/GameToolsPresenterProvider.dart (Run flutter format to format lib/game/tools/GameToolsPresenterProvider.dart.)
  • lib/game/tools/GameToolsView.dart (Run flutter format to format lib/game/tools/GameToolsView.dart.)
  • lib/game/tools/area/area_interactor.dart (Run flutter format to format lib/game/tools/area/area_interactor.dart.)
  • lib/game/tools/designer/game_designer_character.dart (Run flutter format to format lib/game/tools/designer/game_designer_character.dart.)
  • lib/game/tools/designer/tools_element_controller_repo.dart (Run flutter format to format lib/game/tools/designer/tools_element_controller_repo.dart.)
  • lib/game/tools/elementKinds/ElementKindsToolsInteractor.dart (Run flutter format to format lib/game/tools/elementKinds/ElementKindsToolsInteractor.dart.)
  • lib/game/tools/elementKinds/ElementKindsToolsPresenter.dart (Run flutter format to format lib/game/tools/elementKinds/ElementKindsToolsPresenter.dart.)
  • lib/game/tools/elementKinds/ElementKindsToolsPresenterProvider.dart (Run flutter format to format lib/game/tools/elementKinds/ElementKindsToolsPresenterProvider.dart.)
  • lib/game/tools/elementKinds/ElementKindsToolsView.dart (Run flutter format to format lib/game/tools/elementKinds/ElementKindsToolsView.dart.)
  • lib/kgress.dart (Run flutter format to format lib/kgress.dart.)
  • lib/main.dart (Run flutter format to format lib/main.dart.)

Maintenance issues and suggestions

Support latest dependencies. (-20 points)

The version constraint in pubspec.yaml does not support the latest published versions for 2 dependencies (flame, optional).

The package description is too short. (-20 points)

Add more detail to the description field of pubspec.yaml. Use 60 to 180 characters to describe the package, what it does, and its target use case.

Maintain an example. (-10 points)

Create a short demo in the example/ directory to show how to use this package.

Common filename patterns include main.dart, example.dart, and kgress.dart. Packages with multiple examples should provide example/

For more information see the pub package layout conventions.

Package is pre-v0.1 release. (-10 points)

While nothing is inherently wrong with versions of 0.0.*, it might mean that the author is still experimenting with the general direction of the API.


Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.1.0 <3.0.0
character_talk ^0.0.5 0.0.5
cupertino_icons ^0.1.2 0.1.3
flame ^0.15.1 0.15.2 0.17.3
flutter 0.0.0
logging ^0.11.3+2 0.11.4
optional ^3.0.0 3.1.0 4.0.1
Transitive dependencies
archive 2.0.13
args 1.5.2
audioplayers 0.13.7
box2d_flame 0.4.5
charcode 1.1.2
collection 1.14.11 1.14.12
convert 2.1.1
crypto 2.1.4
flare_dart 2.3.3
flare_flutter 1.8.3 2.0.1
flutter_svg 0.14.4 0.15.0
meta 1.1.8
ordered_set 1.1.5
path 1.6.4
path_drawing 0.4.1
path_parsing 0.1.4
path_provider 1.5.1
petitparser 3.0.0
platform 2.2.1
sky_engine 0.0.99
synchronized 2.1.1
tiled 0.2.1
typed_data 1.1.6
uuid 2.0.4
vector_math 2.0.8
xml 3.7.0
Dev dependencies
mockito 4.0.0
test ^1.5.3