{"id":19347849,"url":"https://github.com/korlibs/korge-fleks","last_synced_at":"2025-04-23T05:32:37.676Z","repository":{"id":64851795,"uuid":"557804958","full_name":"korlibs/korge-fleks","owner":"korlibs","description":"Fleks Entity Component System integration for KorGE Game Engine","archived":false,"fork":false,"pushed_at":"2024-11-06T18:19:09.000Z","size":778,"stargazers_count":10,"open_issues_count":0,"forks_count":0,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-11-06T19:27:52.110Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/korlibs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-26T10:39:26.000Z","updated_at":"2024-10-23T10:48:09.000Z","dependencies_parsed_at":"2023-12-22T17:25:49.754Z","dependency_job_id":"2a7a307d-22d6-47ac-a9f0-25b7eddd628d","html_url":"https://github.com/korlibs/korge-fleks","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/korlibs%2Fkorge-fleks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/korlibs%2Fkorge-fleks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/korlibs%2Fkorge-fleks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/korlibs%2Fkorge-fleks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/korlibs","download_url":"https://codeload.github.com/korlibs/korge-fleks/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223910370,"owners_count":17223671,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-10T04:18:14.561Z","updated_at":"2024-11-10T04:18:15.134Z","avatar_url":"https://github.com/korlibs.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# KorGE-Fleks\n\n\nThis is the [Fleks Entity Components System](https://github.com/Quillraven/Fleks) (ECS) integration for KorGE Game Engine.\n\nKorGE-Fleks consists of a growing set of Entity Component definitions, dedicated Entity Systems and utilities around\nthem like AssetStore, Entity-Component serialization, etc. which are reusable or will get better reusable over time.\nEventually this will grow into a specialized KorGE-based Game Engine for 2D platform games.\n\nUpstream project for Fleks ECS can be found here: \u003chttps://github.com/Quillraven/Fleks\u003e\n\nKorGE-Fleks is maintained by [@jobe-m](https://github.com/jobe-m)\n\n# Supported Versions\n\nThis is a list of versions for all needed modules/addons which are known to work together with\nKorGE-Fleks:\n\n```\n- KorGE:                v6.0.0-beta4\n- KorGE-LDtk addon:     v1.0.3\n- Fleks:                2.9\n```\n\n# Idea and Motivation\n\nThe KorGE-Fleks implementation follows the idea to separate the configuration of _Game Objects_ from their executed behavior.\n\nA game object in an ECS is an _Entity_ and per definition just an index number (in Fleks e.g. `Entity(id = 1)`).\nRuntime-configuration for a game object can be defined as an _Aspect_ of an entity. The aspects of an entity are stored in a\n_Component_. An entity usually has multiple components assigned. _Systems_ iterate over all active entities of an ECS world\nand execute the \"behavior\" for each Entity. To do so systems use the properties from all associated components of an entity.\n\nIf I lost you already please step back and read elsewhere a little more about ECS basics. It is important to\nunderstand -at least- the basic principles of an ECS system. Moreover, there are various interpretations out there what\nan ECS is and how it works. But when you read further down you should get the idea of how the Fleks ECS can work\nwithin a KorGE game.\n\nPer definition KorGE-Fleks components contain only data which is necessary to fully describe the state of a game\nobject at every point in time. All components are easily serializable with _kotlinx.serialization_ because of its\nbasic nature. This enables the game system to save the state of a game object and to restore its state\nwhen needed. This also makes it possible to easily implement a save-game system or to handle transmission of game object\nstates over network for a multiplayer game. Details about implemented property types for components can be found below in\nsection Components.\n\nKorGE-Fleks can save the state of the game by simply serializing and saving the whole ECS world snapshot as a JSON string\nto a file (all active entities and components). Loading a saved state of the game is done by deserializing the\nsaved JSON string of a world\nsnapshot.\n\nKorGE-Fleks implements a couple of useful Systems. Those systems keep track of complex KorGE objects and map them\nto the Entities which needs those objects to implement various behavior like e.g. displaying sprites, playing sounds or\nreacting to touch input.\n\nExecution time of systems in Fleks is very static and thus predictable. The core of KorGE makes a lot of use of\ncoroutines and asyncronous execution of object's behavior in update functions. KorGE-Fleks tries to hide this\ncomplexity in the implemented systems.\n \nAssetStore implements loading of typical game asses like graphics images, sounds, level maps, game object configs, etc.\nIt uses up to 4 independently loadable sets of asset which can have different lifetime in the game:\n- Common assets\n- World assets\n- Level assets\n- Special assets\n\nKorGe-Fleks provides basic entity configuration objects and functions to easily setup Game Objects \n\n- Parallax background\n- Text and image logos\n- Level maps (Tiledmap)\n- Effect objects (like explosions)\n- ... to be continued\n\nIn the end the actual game code outside KorGE-Fleks is just specialized configuration and individual assets for the\nfinal Game Objects.\n\n# Implementation of KorGE-Fleks\n\nThis repository contains under `korge-fleks/src` folder the _KorGE-Fleks_ addon. The next subsection gives an overview\nover all provided Components and Systems. Also, Serialization of Entities and its associated components and how to\nuse the AssetStore and entity configuration to build up Game Objects is described.\n\n## Components\n\nAll provided components in KorGe-Fleks contain only basic property types like:\n\n- String\n- Number (Int, Float, Double)\n- Enum class (like Easing from KorGE)\n- Entity (Int value class)\n- Identifier (String value class for accessing static entity configuration which is loaded from AssetStore and\n  invoking functions with `World`, `Entity` and `Identifier` parameters)\n\nCollections of above types in Lists and Maps are also supported.\n\nFor simplicity all properties are independent of any KorGE-specific complex classes. Components do not contain\nany KorGE-related complex objects like `Views`, `Image`, `Camera`, etc.\n\nHint: Where it makes sense a basic type can be taken over from KorGE as it is done with the `Easing` enum class for the\n_Animation system_.\n\n## Serialization of Components\n\n... to be continued\n\n## Systems\n\n...\n\n## Entity Configuration\n\nKorGE-Fleks contains some generic configuration assets which can be used to build up more complex game objects.\nThe existing config objects can be found in `korlibs.korge.fleks.entity.config`.\nThese object classes contain 4 sections:\n\n- Config data classes\n- Identifiers for invokable functions\n- The actual (anonymous) configure function as a value object\n- Init block which registers the configure function and its Identifier to the Invokable object store\n\nA configuration for an entity is applied to the entity's components by executing\nthe configure function. The Invokable object stores the relationship between the Identifier and the function.\nSystems like the SpawnerSystem will invoke the function by looking up the Identifier and executing invoke from\nthe Invokable object class. This is how KorGE-Fleks can set up new game objects/entities in a very generic and\nconfigurable way. \n\n## AssetStore\n\n...\n\n### Hot-reloading of Assets\n\n...\n\n## Fleks World Integration into a KorGE Scene\n\n...\n\n# Set up a new Game with KorGE-Fleks\n\nAs a clean start the [KorGE-Fleks Hello World](https://github.com/korlibs/korge-fleks-hello-world) repository can be used.\nIt contains the kproject and gradle setup to use Fleks, KorGE and KorGE addons _KorGE-Fleks and KorGE-LDtk in a project.\n\nIn detail the project setup looks like that:\n\n## `build.gradle.kts`\n\nThis tells gradle that the overall project depends on a project _deps_ in the root directory.\n\n```kotlin\n[...]\ndependencies {\n    add(\"commonMainApi\", project(\":deps\"))\n}\n```\n\n## `deps.kproject.yml`\n\nThis is the configuration for kproject to set up a project _deps_ in the root directory.\nIt just contains one dependency to the KorGE-Fleks addon.\n\n```yaml\ndependencies:\n    - https://github.com/korlibs/korge-fleks/tree/0acbfcb5d89eca161c3537a9160143c9a72d2725/korge-fleks\n#    or use local copy\n#    - ./submodules/korge-fleks/korge-fleks\n```\n\n## `settings.gradle.kts`\n\nNeeded settings for gradle to make kproject usable in the project.\n\n```kotlin\npluginManagement {\n    repositories { mavenLocal(); mavenCentral(); google(); gradlePluginPortal() }\n}\n\nbuildscript {\n    val libsTomlFile = File(this.sourceFile?.parentFile, \"gradle/libs.versions.toml\").readText()\n    var plugins = false\n    var version = \"\"\n    for (line in libsTomlFile.lines().map { it.trim() }) {\n        if (line.startsWith(\"#\")) continue\n        if (line.startsWith(\"[plugins]\")) plugins = true\n        if (plugins \u0026\u0026 line.startsWith(\"korge\") \u0026\u0026 Regex(\"^korge\\\\s*=.*\").containsMatchIn(line)) version = Regex(\"version\\\\s*=\\\\s*\\\"(.*?)\\\"\").find(line)?.groupValues?.get(1) ?: error(\"Can't find korge version\")\n    }\n    if (version.isEmpty()) error(\"Can't find korge version in $libsTomlFile\")\n\n    repositories { mavenLocal(); mavenCentral(); google(); gradlePluginPortal() }\n\n    dependencies {\n        classpath(\"com.soywiz.korge.settings:com.soywiz.korge.settings.gradle.plugin:$version\")\n    }\n}\n\napply(plugin = \"com.soywiz.korge.settings\")\n```\n\n## `fleks/kproject.yml`\n\nThis is the kproject config for including Fleks sources into the KorGE project. Since `Entity` value objects\nfrom Fleks need to be serializable for saving the game state the `serialization` plugin needs to be added.\n\n```yaml\n# Get an external source project from GitHub which does not contain a kproject.yml file\n# loading git tag release (or commit) from GitHub repo (https://github.com/Quillraven/Fleks)\nsrc: git::Quillraven/Fleks::/src::2.9\n\nplugins:\n    - serialization\n```\n\n## `korge-fleks/kproject.yml`\n\nThis is the kproject config for including KorGE-Fleks sources into the KorGE project. Also for KorGE-Fleks\nthe `serialization` plugin is needed to save the game state.\n\n```yaml\nplugins:\n    - serialization\n\ndependencies:\n    - ../fleks\n# Or use fleks locally\n#  - ../../fleks\n#\n    - maven::common::com.soywiz.korlibs.korge2:korge\n    - https://github.com/korlibs/korge-ldtk/tree/v1.0.3/korge-ldtk\n# Use local copy of KorGE addons\n#    - ../../korge-ldtk/korge-ldtk\n```\n\n## `korge-ldtk/kproject.yml`\n\nThis is the kproject config for KorGE-LDtk sources. It basically contains only the dependency\nof KorGE-LDtk to KorGE.\n\n```yaml\nname: \"korge-ldtk\"\nplugins:\n    - serialization\ndependencies:\n    - \"maven::common::com.soywiz.korlibs.korge2:korge\"\n```\n\nThere is also a kproject files for the other KorGE-addons. They look basically the same as that one for\n`korge-ldtk` and therefore is omitted here.\n\nWhen changes are needed in one of the kproject libs above than it is possible to use a local copy of the\ncorresponding git repo in the `modules` folder. E.g. for KorGE-LDtk the `src:` line with git details can be\ncommented out and the `src:` line with local folder under `../../korge-ldtk/korge-ldtk` can be\nuncommented.\n\n# Updating KorGE-Fleks to newer versions\n\nKorGE-Fleks depends on specific versions of KorGE, KorGE-Ldtk addon and Fleks ECS.\n\nThe current versions which are working together can be seen at the top of this readme in section\n\"Supported Versions\".\n\nKorGE, Fleks ECS and all KorGE Addon versions need to be updated in following places:\n\n## KorGE version\n\nKorGE version needs to be updated in `gradle/libs.versions.toml`:\n\n```toml\n[plugins]\nkorge = { id = \"com.soywiz.korge\", version = \"5.4.0\" }\n```\n\n## Fleks version\n\nFleks ECS version needs to be updated in the kproject file under `fleks/kproject.yml`:\n\n```yaml\n[...]\nsrc: git::Quillraven/Fleks::/src::2.x\n```\n\n## KorGE Addon versions\n\nAll versions of additionally used KorGE addons (KorGE-LDtk) needs to be updated\nin KorGE-Fleks kproject file under `korge-fleks/kproject.yml`:\n\n```yaml\n[...]\ndependencies:\n[...]\n- https://github.com/korlibs/korge-ldtk/tree/v1.0.x/korge-ldtk\n```\n\n# Examples\n\n* [Korge-fleks-hello-world example](https://github.com/korlibs/korge-fleks-hello-world)\n\n  \u003cimg width=\"546\" alt=\"Screenshot 2022-10-26 at 13 54 12\" src=\"https://user-images.githubusercontent.com/570848/198019508-dafdb3a5-02af-49f7-92ec-9f76533c2524.png\"\u003e\n\n* [KorGE-Fleks Hello World](https://github.com/korlibs/korge-fleks-hello-world)\n\n# History\n\n* \u003chttps://github.com/korlibs-archive/korge-next/pull/472\u003e\n* \u003chttps://github.com/korlibs/korge/pull/988\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkorlibs%2Fkorge-fleks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkorlibs%2Fkorge-fleks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkorlibs%2Fkorge-fleks/lists"}