Bot extension

Table of Contents

Introduction
How to start?
Development
- Extension lifecycle
- Example
Deploying bot extension to bot server

Introduction

Bot extension allows you to write a custom bot logic.

Bot extension is wriiten in Java.

You will need the following tools:

It’s also good to know:

Gradle Build Tool which is used to manage java projects.

How to start?

Contact us and request a bot server for your game.
1. Provide us with:
  - your bot extension class name
    
    name it according to the following pattern:
    
    {package-name}.{project-name}BotExtension
    
    for example: RummyBotExtension
  - your bot extension package name
2. You’ll receive:
  - development bot server
  - production bot server
  - development bot server bot extension upload url
  - production bot server bot extension upload url
  - bot extension upload username and password
  - bot extension library jar name
  - access to bot server logs
Put bot server upload configuration into global gradle.properties file.
1. Global gradle.properties file is located:
  - in $HOME/.gradle/gradle.properties on Linux
  - in $HOME/.gradle/gradle.properties on Mac
  - in %userprofile%\.gradle\gradle.properties on Windows
2. Add the following lines:
  {project.deploy.config.prefix}.botserver.prod.url={bot-extension-production-upload-url} {project.deploy.config.prefix}.botserver.dev.url={bot-extension-development-upload-url} {project.deploy.config.prefix}.botserver.username={bot-extension-upload-username} {project.deploy.config.prefix}.botserver.password={bot-extension-upload-password}
  Replace project.deploy.config.prefix with your project name in lowercase.
  
  You’ll also set it in your project configuration in a moment.
3. Example global gradle.properties file:
  rummy.botserver.prod.url=https://dev.lite-games.com/repository/rummy/prod rummy.botserver.dev.url=https://dev.lite-games.com/repository/rummy/dev rummy.botserver.username=rummy rummy.botserver.password=password
4. Bot server upload urls, username and password are kept in global gradle.properties file to avoid commiting them into repository for security reasons.
Download Smarty Alpha Bot Extension zipped project and use it as a base for your bot extension project.
```
curl -O https://bitbucket.org/litegames/smarty-alpha-bot-extension/get/master.zip
```

Unzip it, rename the directory and setup up a git repository

unzip master.zip
mv litegames-smarty-alpha-bot-extension* \{project-name}-bot-extension/
cd \{project-name}-bot-extension/
git init

Build project using gradle.

This is to make IntelliJ see generated sources properly.
```
./gradlew clean build
```
Open project in IntelliJ IDEA
1. When you’ll be prompted with Unlinked Gradle project? click on Import Gradle project link and click OK in the next dialog.
Open bot-extension/gradle.properties and configure it for your project
1. Fill in the following gaps:
  project.name=\{project-name} project.package.name=\{project-package-name} project.deploy.config.prefix={project-deploy-config-prefix} project.deploy.jar.name={bot-extension-jar-name}
  - project-name - your project name
  - project-package-name - your main package name
  - project-deploy-config-prefix - same prefix that you choose for settings in global gradle.properties file
  - bot-extension-jar-name - bot extension jar name that you received
2. Example bot-extension/gradle.properties file:
  project.name=Rummy project.package.name=com.litegames.rummy project.deploy.config.prefix=rummy project.deploy.jar.name=RummyBotExtension.jar
Rename SmartyAlphaBotExtension class into {project-name}BotExtension.
1. Open SmartyAlphaBotExtension class with Navigate/Class…
2. Select the class name and rename it with Refactor/Rename…
Rename com.litegames.smarty.alpha.game package into {project-package-name}.
1. Open SmartyAlphaBotExtension class with Navigate/Class…
2. Select package name located on top of the file
3. Rename it with Refactor/Rename…
4. If warned about Multiple directories correspond to package select Rename package
Rebuild project with Build/Rebuild Project to see if everything is ok.
Now you have a base project set up for your bot extension development.

Commit all your changes

git add .
git commit -m "Initial commit"

Tag initial version 0.0.0
```
git tag -a 0.0.0 -m ""
```
Bot extension reports its version to bot server.

Bot extension version is determined from git tag (precisely it is taken from git describe --tags --dirty --always command).

Configure your remote repository server

git remote add origin {server-url}
git push -u origin master

Push changes to your git respository server
```
git push && git push --tags
```

Development

Main goal of a bot extension development is to implement BotExtension interface.

There are several versions of the BotExtension interface: BotExtension, BotExtension2, BotExtension3. Always choose the newest one.

Here is the current version:

public interface BotExtension3 {
    String getVersion();
    void onInit(Smarty smarty);
    void onDestroy();
    void onMatchStart(Smarty smarty, GameRoom gameRoom);
}

Class implementing BotExtension interface will be instantiated by the bot on the bot server.

Bot will create BotExtension just before a match and destroy it a moment after a match will finish.

You are responsible for providing a version of your bot extension. It will be visible in bot server logs and will ease future debugging.

Extension lifecycle

Bot will call onInit extension method right after creating it. It can be used to setup some smarty listeners beforehand.

When the match is going to start, bot will call onMatchStart extension method and pass it smarty object and current game room.

onDestroy extension method will be called right before releasing a bot extension object.

Example

Smarty Alpha Bot Extension project is a good example of bot extension implementation.

Check it if you have any problems.

Deploying bot extension to bot server

Deploy allow you to update your bot logic on the bot server.

Update is performed on a live server (it doesn’t require bot server restart).

After an update, new matches will use new bot extension. Matches that are still in progress will be continued using old bot extension.

Commit all your changes
```
git commit -m "{message}"
```
Tag new version
```
git tag -a x.y.z -m ""
```
Push your changes to remote repository
```
git push && git push --tags
```
Build your extension
```
./gradlew clean build
```

Deploy your extension

to development server
```
./gradlew deployDevelopmentBotExtension
```
or to production server
```
./gradlew deployProductionBotExtension
```