{"id":26194764,"url":"https://github.com/benpollarduk/ktaf","last_synced_at":"2025-04-15T03:15:25.034Z","repository":{"id":197042867,"uuid":"696256399","full_name":"benpollarduk/ktaf","owner":"benpollarduk","description":"A Kotlin library that provides a framework for creating text adventures and interactive stories for JVM. Ktaf is a Kotlin implementation of NetAF.","archived":false,"fork":false,"pushed_at":"2024-10-31T23:55:18.000Z","size":863,"stargazers_count":12,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-15T03:15:20.739Z","etag":null,"topics":["adventure","engine","framework","game","game-engine","interactive","interactive-story","java","kotlin","story","text","text-adventure"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/benpollarduk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2023-09-25T12:00:37.000Z","updated_at":"2024-11-03T07:18:34.000Z","dependencies_parsed_at":null,"dependency_job_id":"4f84ec5a-d860-4231-9ec8-f2ccccb1c3c6","html_url":"https://github.com/benpollarduk/ktaf","commit_stats":null,"previous_names":["ben-pollard-uk/ktaf"],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benpollarduk%2Fktaf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benpollarduk%2Fktaf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benpollarduk%2Fktaf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benpollarduk%2Fktaf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/benpollarduk","download_url":"https://codeload.github.com/benpollarduk/ktaf/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248997080,"owners_count":21195799,"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":["adventure","engine","framework","game","game-engine","interactive","interactive-story","java","kotlin","story","text","text-adventure"],"created_at":"2025-03-12T01:59:56.133Z","updated_at":"2025-04-15T03:15:25.010Z","avatar_url":"https://github.com/benpollarduk.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Ktaf\n\nA Kotlin library that provides a framework for creating text adventures and interactive stories for JVM. Ktaf is a Kotlin implementation of NetAF. \nKtaf aims to provide all of the basic building blocks required to start writing simple games.\n\n[![main-ci](https://github.com/benpollarduk/ktaf/actions/workflows/main-ci.yml/badge.svg?branch=main)](https://github.com/benpollarduk/ktaf/actions/workflows/main-ci.yml)\n[![codecov](https://codecov.io/gh/benpollarduk/ktaf/graph/badge.svg?token=1C7HRFJ6C9)](https://codecov.io/gh/benpollarduk/ktaf)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=benpollarduk_ktaf\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=benpollarduk_ktaf)\n[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=benpollarduk_ktaf\u0026metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=benpollarduk_ktaf)\n[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=benpollarduk_ktaf\u0026metric=security_rating)](https://sonarcloud.io/summary/new_code?id=benpollarduk_ktaf)\n[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=benpollarduk_ktaf\u0026metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=benpollarduk_ktaf)\n[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=benpollarduk_ktaf\u0026metric=bugs)](https://sonarcloud.io/summary/new_code?id=benpollarduk_ktaf)\n[![GitHub release](https://img.shields.io/github/release/benpollarduk/ktaf.svg)](https://github.com/benpollarduk/ktaf/releases)\n[![License](https://img.shields.io/github/license/benpollarduk/ktaf.svg)](https://opensource.org/licenses/MIT)\n[![Documentation Status](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://benpollarduk.github.io/ktaf-docs/)\n\n\u003c/div\u003e\n\n## Overview\nIncluded in the repo are example projects that show how Ktaf can be used to write games that run in a terminal window as originally intended, and also an example Swing application and an example Ktor webserver are also included that render the game in HTML.\n\n![ktaf_example](https://github.com/benpollarduk/ktaf/assets/129943363/10ee7024-f3ea-4679-b50c-011503eac836)\n\nAt its core Ktaf provides simple classes for developing game elements:\n\n### Environments\nEnvironments are broken down in to three elements - Overworld, Region and Room. An Overworld contains one or more Regions. A Region contains one or more Rooms. \nA Room can contain up to six exits (north, south, east, west, up and down).\n\n```\nOverworld\n├── Region\n│   ├── Room\n│   ├── Room\n│   ├── Room\n├── Region\n│   ├── Room\n│   ├── Room\n```\n\n### Exits\nRooms contain exits. Exits can be locked to block progress through the game.\n\n```kotlin\n// create a test room\nval room = Room(\"Test Room\", \"A test room.\")\n        \n// add an exit to the north\nroom.addExit(Exit(Direction.NORTH))\n```\n\n### Items\nItems add richness to a game. Items support interaction with the player, rooms, other items and NPC's. Items can morph in to other items. \nFor example, using item A on item B may cause item B to morph into item C.\n\n```kotlin\nval sword = Item(\"Sword\", \"The heroes sword.\")\n```\n\n### Playable Character\nEach Ktaf game has a single playable character. The game is played through the view point of the playable character.\n\n```kotlin\nval player = PlayableChracter(\"Dave\", \"The hero of the story.\")\n```\n\n### Non-playable Characters\nNon-playable characters (NPC's) can be added to rooms and can help drive the narrative. NPC's can hold conversations, contains items, \nand interact with items.\n\n```kotlin\nval npc = NonPlayableChracter(\"Gary\", \"The antagonist of the story.\")\n```\n\n### Commands\nKtaf provides commands for interacting with game elements:\n  * **Drop X** - drop an item.\n  * **Examine X** - allows items, characters and environments to be examined.\n  * **Take X** - take an item.\n  * **Talk to X** - talk to a NPC, where X is the NPC.\n  * **Use X on Y** - use an item. Items can be used on a variety of targets. Where X is the item and Y is the target.\n  * **N, S, E, W, U, D** - traverse through the rooms in a region.\n\nKtaf also provides global commands to help with game flow and option management:\n  * **About** - display version information.\n  * **CommandsOn / CommandsOff** - toggle commands on/off.\n  * **Exit** - exit the game.\n  * **Help** - display the help screen.\n  * **KeyOn / KeyOff** - turn the Key on/off.\n  * **Map** - display the map.\n  * **New** - start a new game.\n\nCustom commands can be added to games without the need to extend the existing interpretation.\n\n### Interpretation\nKtaf provides classes for handling interpretation of input. Interpretation is extensible with the ability for custom interpreters to be added outside of the core Ktaf library.\n\n### Conversations\nConversations can be held between the player and a NPC. Conversations support multiple lines of dialogue and responses.\n\n![image](https://github.com/ben-pollard-uk/ktaf/assets/129943363/3adc4210-2732-4f79-9d19-000af0287f07)\n\n### Attributes\nAll game assets support customisable attributes. This provides the possibility to build systems within a game, for example adding currency and trading, adding HP to enemies, MP to your character, durability to Items etc.\n\n### Rendering\nKtaf provides frames for rendering the various game screens. These are fully extensible and customisable. These include:\n   * Scene frame.\n   * Help frame.\n   * Map frame.\n   * Title frame.\n   * Completion frame.\n   * Game over frame.\n   * Transition frame.\n   * Conversation frame.\n\n### Maps\nMaps are automatically generated for regions and rooms, and can be viewed with the **map** command:\n\n![image](https://github.com/ben-pollard-uk/ktaf/assets/129943363/b8e52974-dad7-4c27-8c0a-6861964a2fbe)\n\nMaps display visited rooms, exits, player position, if an item is in a room, lower floors and more.\n\n### Dynamic Loading\nPrecompiled games can also be discovered and loaded from .jar files at runtime with the GameCatalogResolver.\n```Kotlin\n// load a .jar file and discover all GameTemplate instances\nval catalog = GameCatalogResolver.resolveCatalogFromJar(File(path))\n\n// in this case take the first GameTemplate from the catalog\nval template = catalog.get().first()\n\n// begin execution of the game\nGameExecutor.execute(gameTemplate, ioConfiguration = AnsiConsoleConfiguration)\n```\n\n## Prerequisites\nThe default frame collections for rendering in a terminal assume that a terminal capable of handling ANSI is being used. If a terminal that doesn't support ANSI is used the game will still render but ANSI will also be displayed as text.\n\n## Getting Started\n\n### Clone the repo\nClone the repo to the local machine.\n```bash\ngit clone https://github.com/benpollarduk/ktaf.git\n```\n\n### Hello World\n```kotlin\n// create a game template. this template can be use to instantiate instances of the game\nval template = object : GameTemplate() {\n\n    override fun instantiate(ioConfiguration: IOConfiguration): Game {\n\n        // create the player. this is the character the user plays as\n        val player = PlayableCharacter(\"Dave\", \"A young boy on a quest to find the meaning of life.\")\n\n        // create region maker. the region maker simplifies creating in game regions. a region contains a series of rooms\n        val regionMaker = RegionMaker(\"Mountain\", \"An imposing volcano just East of town.\").also {\n            // add a room to the region at position x 0, y 0, z 0\n            it[0, 0, 0] = Room(\"Cavern\", \"A dark cavern set in to the base of the mountain.\")\n        }\n\n        // create overworld maker. the overworld maker simplifies creating in game overworlds. an overworld contains a series or regions\n        val overworldMaker = OverworldMaker(\"Daves World\", \"An ancient kingdom.\", listOf(regionMaker))\n\n        // return a new instance of the game\n        return Game(\n            GameInformation(\n                \"The Life Of Dave\",\n                \"Dave awakes to find himself in a cavern...\",\n                \"A very low budget adventure.\",\n                \"Me\",\n            ),\n            player,\n            overworldMaker.make(),\n            { EndCheckResult.notEnded },\n            { EndCheckResult.notEnded },\n        )\n    }\n}\n\n// begin execution of the game. the ioConfiguration determines how input is received and output is displayed\nGameExecutor.execute(template, ioConfiguration = ioConfiguration)\n```\n\n### Tutorial\nThe quickest way to start getting to grips with Ktaf is to take a look at the [Getting Started](https://benpollarduk.github.io/ktaf-docs/getting-started/) page.\n\n### Example game\nAn example game is provided in the [ktaf-exmples](https://github.com/benpollarduk/ktaf/tree/main/ktaf-example/src/main/kotlin/com/github/benpollarduk/ktaf/example) directory  and have been designed with the aim of showcasing the various features.\n\n### Running the examples\nThe example applications can be used to execute the example Ktaf game and demonstrate the core principals of the framework.\n\n#### Example console\nThe example console provides a basic terminal application that can execute a Ktaf game.\n* Build the example console application.\n```bash\n./gradlew clean :app-ktaf-example-console:build\n```\n* Run the example console application.\n```bash\ncd app-ktaf-example-console/build/libs\njava -jar app-ktaf-example-console-all.jar\n```\n\n#### Example Swing application\nThe example Swing application provides a basic UI that can execute a Ktaf game.\n* Build the example Swing application.\n```bash\n./gradlew clean :app-ktaf-example-swing:build\n```\n* Run the example Swing application.\n```bash\n./gradlew :app-ktaf-example-swing:run\n```\n\n#### Example Ktor web app\nThe example Ktor web app provides a basic web server that can host a Ktaf game and display it in the browser.\n* Build the example Ktor application.\n```bash\n./gradlew clean :app-ktaf-example-ktor:build\n```\n* Run included ktor example webserver then navigate to localhost:8080 in browser.\n```bash\n./gradlew :app-ktaf-example-ktor:run\n```\n\n## Documentation\nPlease visit [https://benpollarduk.github.io/ktaf-docs/](https://benpollarduk.github.io/ktaf-docs/) to view the Ktaf documentation.\n\nPlease visit [https://benpollarduk.github.io/ktaf-api-docs/](https://benpollarduk.github.io/ktaf-api-docs/) to view the Ktaf Api documentation.\n\n## For Open Questions\nVisit https://github.com/benpollarduk/ktaf/issues\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenpollarduk%2Fktaf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbenpollarduk%2Fktaf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenpollarduk%2Fktaf/lists"}