installation_instructions.txt

Caller's Bane server setup instructions

===================================================================================================================
  MANDATORY: Installation
===================================================================================================================

This guide assumes you'll be installing the server on a recent version of Windows (64-bit). It also assumes you have Java installed (versions 7/8 have been tested). It should be relatively straightforward to adapt this process to other operating systems.

1. Download MySQL 5.7.x (*)
	(Mojang and Microsoft are not affiliated with MySQL and make no guarantees regarding its safe use or features)

	1a) For the simplest setup, download the MySQL Installer:
		- MySQL Installer
			https://dev.mysql.com/downloads/installer/5.7.html#downloads

	1b) Alternatively, download and and setup:
		- MySQL Community Server (GPL)
			https://dev.mysql.com/downloads/mysql/5.7.html#downloads

2. This step assumes you chose option 1a. Run the MySQL Installer:

	2a) When chosing Setup Type, the "Server" option should work well.

	2b) If "Check Requirements" comes up and mentions failing requirements, you can safely ignore this and just click "Next". Click past the the dialog that says not all requirements have been satisfied.

	2c) In the Installation section, click Execute. This should install the necessary database software. 

		- If the installation goes wrong in any way, it may be that you do not have sufficient administrator privileges. Try following the steps below:

			* Run the installer program again, then hit the "Remove ..." button. Select all products and hit "Execute". Once all programs have been removed, close and re-open the installer. Next, during Setup Type, choose "Custom". Look for the "MySQL Server X.X.XX - X64" product and add it by clicking the right arrow.

			* Select the MySQL server to the right, then click "Advanced Options" in the bottom right corner. Change the "Install Directory" to something outside of Program Files, for example a folder on your desktop.

	2d) You should be able to use the default settings for the rest of the installation. If the installer asks you to provide a root password for the MySQL server, input a password, and make sure you have it available for later in this guide.

3. Import the Caller's Bane database into your MySQL setup:

	- Go to the folder where you installed MySQL (usually C:\Program Files\MySQL\MySQL Server X.X\) and navigate to the "bin" folder.
	- Copy the included "callersbane_database.sql" file from the Caller's Bane server folder into the folder you just navigated to.
	- Open a command prompt ("File -> Open Windows PowerShell"). Next, run the following commands to import the database:
		* cmd.exe
		* mysql.exe -u root -p < callersbane_database.sql
		This last command will prompt you for your password from 2d. Input it. The command may take a few minutes to finish.

4. In your Caller's Bane server folder, navigate to the "cfg" folder, then open hibernate.cfg.xml with a text editor, such as Notepad or TextEdit. Between "<property name="hibernate.connection.password">" and "</property>", type in the password you selected in step 2d. Save the file.

5. Go back to the Caller's Bane server folder, and run the "localserver.bat" file to start the server. Hopefully, it should spit out some text, and then be good to go. If this shows a Windows popup asking for network permissions, click OK.

6. You should now be able to connect to the server from the client. Try opening the Caller's Bane client, making sure you're not logged into any server, and then click "edit servers". Type in "localhost # localhost" on a new line, hit OK, then select the localhost server from the dropdown and connect to it.



If you had problems starting the server or getting "cannot find Server.jar" errors while starting it, make sure the Caller's Bane server folder is in a folder path without special characters (such as Ö or ñ). If you're unsure what this means, it's safer to put it in C:\CallersBaneServer than in your Documents folder or on your Desktop.

(*) It's possible to use other versions of MySQL as well, but this one has been tested. If you version 8.0 or greater, you will need to manually disable caching_sha2_password. See this page for more information: https://dev.mysql.com/doc/refman/8.0/en/caching-sha2-pluggable-authentication.html . If you absolutely want to use caching_sha2_password, it may be possible to replace the version of connector/j being used (mariadb-java-client-1.4.6.jar) with some library that supports this. This requires changing the hibernate.xml file inside Server.jar.



===================================================================================================================
  OPTIONAL: Admin account, moderators, system accounts
===================================================================================================================

If you want to have an admin account (which has access to a host of chat commands - try /help), you'll need to edit the database (using a database editor or plain SQL). We recommend using something like HeidiSQL, which is a free and very powerful database editor (Mojang and Microsoft are not affiliated with HeidiSQL and make no guarantees regarding its safe use or features). Please note that not all database editors play well with all versions of MySQL.

With HeidiSQL, connect to the database ("scrolls" at 127.0.0.1), using your root user and password from 2d.

The profiles table in the database contains all existing users on your server. To make yourself an admin, first make an account on the server (using the client), then connect to the database and change your profile's admin_role record to "Admin" (in the "profiles" table). Next time you log in, you'll have full admin rights. You can also give users moderator privileges by giving them the "Moderator" role. Moderators have access to some chat commands, but not all of them.

Once you have admin rights, you can set a master password that's used for accessing the system accounts. The most notable ones are DeckTemplate, RobotEasy, RobotMedium, RobotHard, RobotTower and RobotTutorial. These accounts contain the various decks used by the AI, as well as the starter decks and the decks sold in the store. To do this, use the following admin chat command: "/resetSystemPassword [yourPassword]". The password cannot contain spaces.



===================================================================================================================
  OPTIONAL: Database configuration
===================================================================================================================

vars:

The vars table has a large number of configuration settings that affect the server and the game in general. Each setting has a comment next to it, so this table should be fairly self-explanatory.

------------------------------

card_types:

The card_types table holds all of the cards in the game.
name: Card name
rules: A comma-separated list of rules that apply to this card. Each rule matches a class that describes its behaviour in the code. Some rules can be followed by (number) to adjust a value belonging to that rule.
flavor: Flavor text
kind: Card type (CREATURE / STRUCTURE / ENCHANTMENT / SPELL)
type: Subtype (Such as Gravelock, Wall, or Lingering)
ap: Attack value
ac: Countdown. -1 means no countdown, in the case of creatures and structures.
hp: Health value
cost_decay / cost_order / cost_growth / cost_energy: Exactly one of these should be greater than 0, to signify the card's cost and faction.
rarity: 0 = common, 1 = uncommon, 2 = rare
public: Is the card visible to players (1) or in development (0)?
set: Which set does the card belong to?
limited_weight: Defaults to 1. Can be weighted up (2) or down (0.5) to make a card more common or less common in Judgement.
tags: These help define things like unit render scale, sound effects and special animations. See the data in the table for examples.
card_image_id: Defines which image is used for the card.
animation_preview_image_id: Which animation preview is used for the card on the board before the animation bundle is loaded?
animation_preview_info: Repositions / scales the animation preview to match the initial state of the animation.
animation_bundle_id: Defines which animation bundle is used for the card.

------------------------------

rule_descs:

name: A name for the rule. This needs to match the class that describes the logic. This is the name used in the "rules" column of the card_types table as well.
displayName: Only used for "traits", that is, rules with italic text. For such rules, the description becomes a hover text.
description: A description of the rule that gets printed on cards (except for traits; see above). Descriptions can make use of macros (such as ${AP} for "Attack") and keywords (such as [Curse] or <Husks>). Keywords are case-insensitive and plural-insensitive, and shows information from the string_maps table. Available macros: ${MOVE}, ${AP}, ${CD}, ${HP}, ${NAME}, ${DECAY/ORDER/GROWTH/ENERGY/WILD}, ${DOMINION}, ${RESONANCE}, ${SURGE}, ${PILLAGE}, ${AMOUNT}, ${NAME}, ${RES}. Of note, ${NAME} refers to the card's name, and ${RES} refers to the resource type of the card.
isPassive: Defines whether a rule is a trait (1) or a normal rule (0).
tags: (Unused)

------------------------------

string_map:

key: A key / name for the string that needs explained.
value: An explanation description that shows up when a card with a highlighted keyword is clicked and flipped over. For this to work, the rule in the rule_descs table needs to mark the keyword with [].

------------------------------

images (stores both card images and animation preview images):

id: Identifier for the image.
data: Binary data for the image. Images are PNGs.
hash: Not used by the game, only by our internal tools. Doesn't matter.

------------------------------

animation_bundles:
id: Identifier for the bundle.
data: Binary data for the animation bundle. Animation bundles are ZIP files.
hash: Not used by the game, only by our internal tools. Doesn't matter.

------------------------------

servers:

The servers table defines a list of servers that is used for the game.
id: An identifier for the server instance.
name: The name of the server. This isn't really shown anywhere.
roles: A comma-separated list of what roles a server has within a server cluster. Allowed roles: LOBBY,GAME,RESOURCE,LOOKUP,JOBS
cluster: A string to determine what cluster the server is in. Each cluster needs to cover each role at least once. You may have multiple servers with GAME roles in a cluster. If so, the LOBBY isn't required to have the GAME role, but it's still allowed. We recommend giving the LOBBY and  any extra GAME servers the RESOURCE role.
connection_count: (Do not modify) Continuously updated connection count for each server.
average_load (Do not modify) What's the load on the server on average?
last_update: (Do not modify) Heartbeat for the server. Each server checks in continuously so that we can see if it's alive.
version: (Do not modify) Server-submitted version number.

IMPORTANT:
- If you're hosting a public server that's accessible to others, you'll need to change your server's IP in the servers table to match your public IP.
- If you're running multiple servers or changing the server id of the default test server, you need to start your servers with a console command that matches the server id. The server comes bundled with a localserver.bat file (for Windows) that holds the startup command for the server. Edit this file with a text editor and change "-Dscrolls.node.id=test-server" to "-Dscrolls.node.id=[your-node-id]", where [your-node-id] (without brackets) matches the server id.

------------------------------

ai_chat_groups / ai_chat_rules:

These two tables define what the AI says in the chat, and when it says it.

------------------------------

hints:

Defines hints shown on the login screen in the game.

------------------------------

jobs:

Defines details about continuous tasks run by the server, such as updating the daily trial, decaying ranked ratings, and etc. You should not change any values here except possibly interval_seconds and next_update. For daily_trial, changing interval_seconds changes to how often new trials are generated. Despite the name, it's fully possible to make these generate more often or less often than daily. If you want to control what time of day these jobs run, you can also adjust the "next_update" timestamp accordingly.

IMPORTANT:
You should not set daily_trial's interval_seconds to anything less than 7200 (every two hours). Doing so may cause it to conflict with the tower_generation job, causing high CPU usage and failure to generate new trials.

------------------------------

profiles:

The profiles table contains all players that have registered with your server, plus a few that are built-in and used for things like the AI or starter decks.
Of note, admin_role defines whether a user is an admin, a moderator, a regular user, or a built-in systems user.

------------------------------

profile_data:

Contains information about each user's current gold, hidden match-making ratings (for quick play and ranked matches, separately), and current level of decay. Also contains user settings such as spectator permissions and willingness to trade or be challenged.

------------------------------

setup_pipes:

The setup_pipes table defines default or special rules for the various ways of playing. This means that game modes can be tweaked in a variety of ways. Each trial is linked to a custom setup_pipe with special rules.
id: An auto-increment id for the setup pipe.
name: A name for the setup pipe.
code: Defines the rules for this setup pipe, if any.

Note in particular the easy_ai, medium_ai and hard_ai setup pipes. These specify that you play against an AI in those matches, and what level the AI has. If the server becomes slow, adjusting these is probably the most efficient way to decrease CPU usage. For example, you might want to change the hard_ai setup pipe to something like "AI(MEDIUM);resources(P2, 2);". This would decrease CPU usage, but increase the challenge slightly by giving the AI more starting resources.

Similarly, you're able to change or add special rules for trials, or alter the rules for any of the game modes, such as Judgement, ranked, or quick match. See the data in the table for examples of what you can do.

------------------------------

store_items:

This table defines what items are available for purchase in the store, and what each item's gold cost is. The Judgement entrance fee is also defined here.

------------------------------

store_item_types:

This table holds the name and description for the various store items.

------------------------------

tower_levels:

This table describes the various pre-defined trials, daily trials, and the tutorial.
id: An auto-incremented id for the trial.
setup_pipe_id: An associated setup pipe that defines the rules of the trial.
name: The trial's name.
deck_name: The name of the deck used by the AI for this trial. If this is NULL, a default AI deck for the connected AI level will be used.
levelDifficulty: The displayed difficulty in the trials menu.
type: TRIAL/DAILY/TUTORIAL.
description: A textual description of the trial. This is automatically generated for DAILY trials.
flavour: A flavor text for the trial that's displayed in the menu.
sort_id: Can be used for inserting trials in the middle of a trial chain, instead of relying on the id field. For example, a trial with sort_id 0.1 is inserted between trial 0 and trial 1.

------------------------------

Enjoy!

/the Caller's Bane team