This project is the Inworld.AI integration for Minecraft Java Edition. It is a plugin to be used with Spigot Minecraft server.
This tutorial documents the development and building the plugin however if you already have a Minecraft server and wish to only deploy the plugin, you may skip to the Deploying section of this documentation.
Note: this documentation references specific version numbers for both Minecraft Java and Spigot server. The latest at this time is 1.20.1. You may need to update to the latest version numbers. Instructions are detailed below on how to do that.
Note: The following installation tutorials reference a previous version of OpenJDK. When following the instructions please ignore the version they list and use 19+.
Note: The following installation tutorials reference a previous version of Maven. When following the instructions please ignore the version they list and use 3.9.0+.
Note: For this project we are using the 1.20.1 version. If a later version is needed please see the instructions below for updating the project to the latest. The commands listed can have the version number changed to the latest.
Once you download the Spigot jar file copy it to the server/ folder at the root of this project. If the folder doesn't exist then create it.
Open your terminal program and navigate to the server/ folder. Type in the following command to start the server java -jar spigot-1.20.1.jar nogui The first time you start the server it will install itself and then shut down. You need to then open a newly created file eula.txt in a text editor and find the line eula=false Change that to eula=true save the file and close the file.
This plugin is based on Spigot 1.20.1 which was the latest at the time of it's release. If a newer version is needed open the pom.xml file located at inworld-plugin/pom.xml from the root of this project. Scroll down to the <dependencies> node and find the <dependency> with the groupId <groupId>org.spigotmc</groupId>. Update the version node <version>1.20.1-R0.1-SNAPSHOT</version> to represent the latest version number and build the plugin following the instructions below.
In VSCode in the Explorer pane, expand the MAVEN section then expand inworld-sdk->Lifecycle and run the package command. It will build the plugin and also copy the compiled file directly to the server\plugins folder.
Open your terminal program and navigate to the server/ folder you installed the Spigot server into. Type in the following command to start the server java -jar spigot-1.20.1.jar nogui to start the server.
To simplify the starting of the server you may wish to create a script file start.bat for Windows or start.sh for Mac and Linux. Create the file in the server/ folder and paste the java -jar spigot-1.20.1.jar nogui command into it. Save and close the file. For Mac and Linux you will need to set the file as executable by running this command in your terminal window: chmod +x start.sh. Examples of these scripts can be located in the scripts/ folder located at the root of this project. You can copy them into the server/ folder but if a newer version from 1.20.1 has been released since the last release of this documention you will need to update them to reflect the latest version number.
If you modify the plugin you can build it while the server is running. In the terminal window running the Spigot server type in the command reload hit enter and this will reload the plugin. Note: Doing this closes any open sessions.
To deploy the plugin to an existing server you can choose a prebuilt version inworld-sdk-1.20.1.jar contained within the builds/ folder located at the root of this project or if you wish to deploy one you've built yourself you may location the build within the server/plugins folder located at the root of this project.
Note: After you add the plugin to the server you will need to either reload or restart it for it to activate.
To setup your Inworld account and add characters to your Minecraft World, follow the instructions in the Admin Commands section. To chat with a character, right click on them and the character will begin the conversation. You can chat with them by hitting the 'T' key, entering your message and then 'Enter' to send the message. This conversation is private between the character and the player.
The conversation will continue as long as the player doesn't move. Once the player has moved in any direction the conversation will pause but can be resumed but right clicking on them again and sending a new chat.
This plugin uses a custom set of Minecraft commands to manage scenes, characters and configure the API Keys to the Inworld REST API. These commands are issued by entering /inworld into the chat window. The commands are tab autocompletion ready to make things easier.
Below are a list of the commands you can issue using the internal Minecraft Java chat window:
set Syntax /inworld api set [key|secret] [String] - This command sets the API Key and Secret to the Inworld REST API service.
list Syntax /inworld api list - This command lists the API hosts for both key and secret.
clear Syntax /inworld api clear [key|secret] - This command will remove the API set for either key or secret.
add Syntax /inworld scene add [sceneId] - This command adds an Inworld scene to the Minecraft server. [sceneId].
characters Syntax /inworld scene characters [sceneId] - This command lists the Inworld characters within a [sceneId].
list Syntax /inworld scene list - This command lists all the Inworld scenes that have been added to the Minecraft server.
remove Syntax /inworld scene remove [sceneId] - This command will remove an Inworld scene from the Minecraft server.
Character - These commands allow you to set, remove and list the characters to the Minecraft game that will add them as Villagers. It also allows you to toggle a character from being stationary vs have Minecraft Villager AI enabled.
add Syntax /inworld character add [character] - This command adds an Inworld scene to the Minecraft server. The [character] id will be tab autocompleted.
list Syntax /inworld character list - This command lists all the Inworld character that have been added to the Minecraft server.
remove Syntax /inworld character remove [character] - This command will remove an Inworld character from the Minecraft server.
toggleAware Syntax /inworld character toggleAware [character] - This command will toggle the AI awareness of the character allowing it to be stationary or act like a regular Minecraft Villager.