From a255a6306ed15cded9e4c6418b8011865ba44f4d Mon Sep 17 00:00:00 2001 From: isuru89 Date: Tue, 9 Mar 2021 15:06:15 +0530 Subject: [PATCH] improve documentation #74 --- README.md | 299 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 220 insertions(+), 79 deletions(-) diff --git a/README.md b/README.md index bf1cc09d..6d916c45 100644 --- a/README.md +++ b/README.md @@ -3,81 +3,225 @@ [![Known Vulnerabilities](https://snyk.io/test/github/isuru89/oasis/badge.svg)](https://snyk.io/test/github/isuru89/oasis) [![coverage](https://codecov.io/gh/isuru89/oasis/branch/master/graph/badge.svg)](https://codecov.io/gh/isuru89/oasis) -# OASIS -Open-source Gamification framework based on Redis. _This project is still under development_ +# OASIS +Open-source Gamification framework based on Redis. + Oasis, is an event-driven gamification framework having ability to define the game rules for events -coming from your applications. This is inspired from Stackoverflow badge system, and extended into +coming from your applications. This is inspired from Stackoverflow badge system, and extended into supporting many game elements, such as, points, badges, leaderboards, milestones, challenges, and ratings. ## Features: - * Different types of customizable gamification elements. (see below) - * Near real-time status updates - * Embeddable game engine - * Users can play in teams - * Modular design, so its easier to extend to your needs - * Out of order event support - -## Supported Gamification Elements +* Different types of customizable [gamification elements](#game-elements). +* Near real-time status updates +* Embeddable game engine +* Users can play in teams +* Modular design, so its easier to extend to the specific needs +* Out of order event support + +## Contents +* [Architecture of Oasis](#architecture-of-oasis) +* [Running Modes](#running-modes) + * [Embedding Engine](#embedding-engine) + * [Engine as a service](#engine-as-a-service) +* [Concepts](#concepts) + * [Participants](#participants) + * [Game Elements](#game-elements) +* [Why Oasis?](#why-oasis) +* [Contributing](#contributing) +* [Roadmap](#roadmap) +* [Kudos!](#kudos) +* [License](#license) + +## Architecture of Oasis +![Oasis Architecture](/docs/images/oasis-arch.png?raw=true "Oasis Architecture") + +* **Events API**: The api can be exposed to public networks where event-sources can publish events to the framework. + This authorize the event sources and game model before accepting any events. +* **Stats API**: This api is for manipulating [game model](#gamification-model) (or in other word admin-related operations) and + querying statistics. Through this API, model entities can be created/updated/removed and those + changes will be reflected in engine too. This API is only for internal purpose. +* **Engine**: This is the heart of the framework which create rewards by evaluating received events based on the defined + rules in the system. + +As of initial version, Redis will act as the database for engine operations considering the performance. + + +## Running Modes + +### Engine as a service + +This is a full deployment with all the components as shown in [Architecture](#architecture-of-oasis). +This provides out-of-the-box components which can be used by your applications. + +For testing purpose, a docker compose has been provided to up and running locally. + +Kubernetes and AWS solution are still pending. + +### Embedding Engine + +One of the important thing about Oasis is that you can embed the game engine +inside your application. In this way, you have to pumping all your events and getting +data/statistics out of Redis. + +Its very simple. + +```java +public static void main(String[] args) { + // load the engine configuration (we use typesafe configs here) + var oasisConfigs = OasisConfigs.defaultConfigs(); + + // initialize the engine database: redis + var dbPool = RedisDb.create(oasisConfigs); + dbPool.init(); + + // required for storing individual events for some game element rules. + // for now you can use the same Redis instance to store events. + var eventStore = new RedisEventLoader(dbPool, oasisConfigs); + + // add elements as you desired for your application + EngineContext context = EngineContext.builder() + .withConfigs(oasisConfigs) + .withDb(dbPool) + .withEventStore(eventStore) + .installModule(RatingsModuleFactory.class) + .installModule(PointsModuleFactory.class) + .installModule(MilestonesModuleFactory.class) + .installModule(ChallengesModuleFactory.class) + .installModule(BadgesModuleFactory.class) + .build(); + + var engine = new OasisEngine(context); + engine.start(); + + engine.submit(event) // you can submit your event(s) now. +} + +``` + +**Note:** Once you start the engine, it will keep running until the application goes down. + +Check the methods of `OasisEngine` class how you can submit your events. + + +## Concepts + +## Participants +It is very important to understand supporting model before going down to the details. +There are four major participants in the system. + +### Entities +#### Game: +A game is a boundary of all game elements. Manipulation of games can only be done by an admin thorugh Stats API. + + +####Player: +A player is an entity who associate with events and get rewarded from elements. +Players can register to the system only by Admins and they will be uniquely identified by email address. +Also Players needs to associate with a game through a team. That means every player must be a member of team. + + +If an event cannot be correlate to a existing player in the system, that event will be discarded and will +not be processed by engine. So, it is important to register all applicable users to the system before such +event is arrived. Still you can add players while the game is running. + +#### Team: +A team is formed by grouping several players together within a game. +A team name must be unique across all games (i.e. system). + +Purpose of a team is to associate players to a game, plus, +provide leaderboards based on awards generated from game rules. +Sometimes it is not fair someone to compete with whole players of a game. + + +#### Event Source: +An external/internal party which generated actual events which can be evaluated by engine. +These event sources must be first registered with the system and download the private key. +Only an Admin can register event sources and map those to games. +And after that, private key must be used to sign the payload of events being dispatched. + +Once received those events to Events API, it will check for the integrity of messages by comparing +the signature and will allow further processing. + + +### Rules of Relationships +Rules of relationship between the above entities can be described as shown below. +* **Rule-1**: There can be many Games running at the same time in a [single deployment](#engine-as-a-service). +* **Rule-2**: A Player can play in many Games at once. +* **Rule-3**: A Player can play a Game _only_ by association with one Team. + Assigning to multiple Teams within a single Game is not allowed. +* **Rule-4**: A Player may change his/her Team, or leave the Game completely. +* **Rule-5**: An Event-Source and Game has a many-to-many relationship, + so that a Game can have multiple sources while a source may push events to multiple games. + + +## Game Elements + +All these game elements, except Attributes and Leaderboards, can be defined in yaml files and register to the engine. +Attributes must be defined when a game is created through admin-api. ### Attributes Each game should define set of awarding attributes to rank some of game elements. For e.g. attributes equivalent in Stackoverflow are gold, silver and bronze. ### Points -One of the core element type in Oasis. The points indicate a measurement about a user against an event. -Users can accumulate points over the time as rules defined by the admin or curator. -Sometimes, points can be negative, hence called penalties. + +_See a sample point specification_ [here](engine/src/test/resources/rules/points-basic.yml) + +One of the core element type in Oasis. The points indicate a measurement about a user against an event. +Users can accumulate points over the time as rules defined by the admin or curator. +Sometimes, points can be negative, hence called penalties. ### Badges + +_See a sample badge specification_ [here](engine/src/test/resources/rules/badges-basic.yml) + A badge is a collectible achievement by a user based on correlating one or several events. Every badge can associate with an attribute. There are several kinds of badges supported by Oasis. - * An event has occurred for the first time (eg: [Stackoverflow Altruist badge](https://stackoverflow.com/help/badges/222/altruist) ) - * An event satisfies a certain criteria (eg: [Stackoverflow Popular Question](https://stackoverflow.com/help/badges/26/popular-question) ) - * For different thresholds can award different sub-badges - * (eg: [Stackoverflow Famous question](https://stackoverflow.com/help/badges/28/famous-question) ) - * Streaks: - * Satisfies a condition for N consecutive times. (eg: [Stackoverflow Enthusiast](https://stackoverflow.com/help/badges/71/enthusiast) ) - * Satisfies a condition for N consecutive times within T time-unit. - * Satisfies a condition for N times within T time-unit. (eg: [Stackoverflow Curious badge](https://stackoverflow.com/help/badges/4127/curious) ) - * Earn K points within a single time-unit (daily/weekly/monthly) - * Eg: [Stackoverflow Mortarboard badge](https://stackoverflow.com/help/badges/144/mortarboard) - * Daily accumulation of an event field is higher than a threshold (T) for, - * N consecutive days. (eg: Earn 50 daily reputation for 10 consecutive days) - * N separate days (eg: Earn 200 daily reputation for 50 consecutive days) - * Manually - * Curators and admin can award badges to players based on non-measurable activities. +* An event has occurred for the first time (eg: [Stackoverflow Altruist badge](https://stackoverflow.com/help/badges/222/altruist) ) +* An event satisfies a certain criteria (eg: [Stackoverflow Popular Question](https://stackoverflow.com/help/badges/26/popular-question) ) + * For different thresholds can award different sub-badges + * (eg: [Stackoverflow Famous question](https://stackoverflow.com/help/badges/28/famous-question) ) +* Streaks: + * Satisfies a condition for N consecutive times. (eg: [Stackoverflow Enthusiast](https://stackoverflow.com/help/badges/71/enthusiast) ) + * Satisfies a condition for N consecutive times within T time-unit. + * Satisfies a condition for N times within T time-unit. (eg: [Stackoverflow Curious badge](https://stackoverflow.com/help/badges/4127/curious) ) +* Earn K points within a single time-unit (daily/weekly/monthly) + * Eg: [Stackoverflow Mortarboard badge](https://stackoverflow.com/help/badges/144/mortarboard) +* Daily accumulation of an event field is higher than a threshold (T) for, + * N consecutive days. (eg: Earn 50 daily reputation for 10 consecutive days) + * N separate days (eg: Earn 200 daily reputation for 50 consecutive days) +* Manually + * Curators and admin can award badges to players based on non-measurable activities. ### Milestones + +_See a sample milestone specification_ [here](engine/src/test/resources/rules/milestone-basic.yml) + Milestone can be created to accumulate points over the lifecycle of a game. It indicates the progress gained by a user. Milestones are always being based on the points scored by a user. -Milestones can be used to give a *rank* to a user based on the current accumulated value. +Milestones can be used to give a *rank* (called Levels in Oasis) to a user based on the current accumulated value. Eg: In Stackoverflow, the total Reputation earned can be defined as a milestone definition and levels can be defined in such a way, - * Scoring 10k reputation - Level 1 - * Scoring 50k reputation - Level 2 - * Scoring 100k reputation - Level 3 - * Scoring 500k reputation - Level 4 - * Scoring 1M reputation - Level 5 - -### Leaderboards -Oasis provides leaderboards based on points scored by users. There are several leaderboards -supported by a game. Such as, - 1. Game Leaderboard - 2. Team Leaderboard +* Scoring 10k reputation - Level 1 +* Scoring 50k reputation - Level 2 +* Scoring 100k reputation - Level 3 +* Scoring 500k reputation - Level 4 +* Scoring 1M reputation - Level 5 -Each leaderboard can be viewed scoped on the time slots. Supported time slots are; daily, weekly, -monthly, quarterly and annually. ### Challenges + +_See a sample challenge specification_ [here](engine/src/test/resources/rules/challenges-basic.yml) + Challenge can be created by a curator at any time of game lifecycle to motivate a user towards a very short term goal. Challenge must have a start time and end time. @@ -85,64 +229,61 @@ A challenge can be scoped to a single user, team, or a game. It also can be defi have single winner or multiple winners. Winners are being awarded First-come basis. A challenge can be completed in two ways, whichever comes first. - * Number of all winners found. - * Time has expired +* Number of all winners found. +* Time has expired ### Ratings + +_See a sample rating specification_ [here](engine/src/test/resources/rules/ratings-basic.yml) + Ratings indicate the current state of a user at a particular time. Based on the events, user's status will be calculated, and from that status, some amount of net points will be awarded. _A user can only be in one state at a time_. A difference between Milestone and Rating would be ratings can fluctuate to any direction, while milestones can only grow. -### Architecture of Oasis -![Oasis Architecture](/docs/images/oasis-arch.png?raw=true "Oasis Architecture") -## Entities in Oasis -There are several entities in Oasis. - 1. Game - 2. User - 3. Event Source - 4. Team - -Relationship between above entities are as below. - 1. There can be many games running at the same time in a single deployment of Oasis. - 2. A user can play in many games at once. - 3. A user can only belong to a single team within a particular game at a time. - 4. A user may change his/her team, or leave the game - 5. An event source can emit different types of events. - 6. A single event type can be multi-cast to any number of games. - 7. All game elements based on those events. +### Leaderboards +Oasis provides leaderboards based on points scored by users. There are several leaderboards +supported by a game. Such as, +1. Game Leaderboard +2. Team Leaderboard + +Each leaderboard can be viewed scoped on the time slots. Supported time slots are; daily, weekly, +monthly, quarterly and annually. + ## Why Oasis? Ultimate objective of the Oasis is to increase the user engagement in applications -through a gamified environment. +through a gamified environment. Oasis might help your applications/community to increase the productivity -and could help in creating a better and enjoyable ride. +and could help in creating a better and enjoyable experience. Following gamifiable environments have been identified. - - SDLC: whole software development lifecycle (coding, bug fixing, deployments) using the - application stack (Code Quality, CI/CD, ALM tools) - - Support Systems: IT helpdesk systems - - Q/A sites: Stackoverflow, Reddit like sites - - Social Networking +- SDLC: whole software development lifecycle (coding, bug fixing, deployments) using the + application stack (Code Quality, CI/CD, ALM tools) +- Support Systems: IT helpdesk systems +- Customer Loyalty frameworks +- Q/A sites: Stackoverflow, Reddit like sites +- Social Networking ## Roadmap - * Character driven game playing - * Narrative Play - * Cloud friendly +* Character driven game playing +* Narrative Play +* Cloud friendly + +## Contributing ## Kudos! This project could not have existed thanks to these awesome open-source projects. - * [Redis](https://redis.io/) - * [Akka](https://akka.io/) - * [Vert.x](https://vertx.io/) - * [Spring-boot](https://spring.io/projects/spring-boot) - * [MVEL](https://github.com/mvel/mvel) - +* [Redis](https://redis.io/) +* [Akka](https://akka.io/) +* [Vert.x](https://vertx.io/) +* [Spring-boot](https://spring.io/projects/spring-boot) +* [MVEL](https://github.com/mvel/mvel) + ## License Apache License - version 2.0 -