Sui Playground

This guide provides step-by-step instructions to manually set up a local Sui development environment, deploy the EVE Frontier world-contracts, and initialize a Smart Gate infrastructure. Credit to [WOLF] Lacal for the original walkthrough posted in Discord.

1. Prerequisites

• Docker or Podman installed, if you use Podman ensure that alias docker=podman is set up for seamless command usage.
  • Windows Users: Docker Desktop is recommended, however you can use WSL2 with Podman if you prefer.
  • Linux Users: Either Podman or Docker works well.
  • Mac Users: Docker Desktop is recommended, but Podman is also supported.
• Git installed to clone repositories.
• Terminal Emulator installed (e.g. Windows Terminal, iTerm2, Ghostty, etc.).
• Text Editor installed (e.g. VSCode, Notepad++, Sublime, NeoVim, etc.).
• Sui CLI (optional on host, but required if you want to interact without docker exec).

winget install --id Microsoft.WindowsTerminal --source winget
winget install --id Microsoft.PowerShell --source winget

The below has been tested in the following configurations:

2. Repository Setup

Clone the core world contracts and the builder scaffold repositories into the same parent directory to ensure the Docker volume mounts work correctly.

2.1 Create a workspace directory

mkdir sui-frontier && cd sui-frontier

2.2 Clone world-contracts and builder-scaffold

git clone https://github.com/evefrontier/world-contracts.git

git clone https://github.com/evefrontier/builder-scaffold.git

Your directory structure should look like this:

sui-frontier/
├── world-contracts/
└── builder-scaffold/

3. Environment Setup

3.1 Verify Volume Mounts

Ensure builder-scaffold/docker/compose.yml correctly points to the world-contracts directory. It should look like this:

volumes:
  - sui-config:/root/.sui
  - ../:/workspace/builder-scaffold
  - ../../world-contracts:/workspace/world-contracts

3.2 Start the Playground

Change into the docker directory of the builder scaffold to access the Docker Compose configuration:

cd builder-scaffold/docker

Build and start the container:

docker compose build

Run the container in detached mode with service ports exposed:

docker compose run -d --name sui-playground --service-ports sui-dev

Wait for the container to initialize. You can check progress with:

docker logs -f sui-playground

Stop following the logs with Ctrl+C when you see Sui dev environment ready.

4. World Contracts Configuration

4.1 Initialize .env

You need to populate the .env files for both world-contracts and builder-scaffold with the keys generated by the container. You can do this automatically from inside the container:

docker exec -it sui-playground /bin/bash /workspace/builder-scaffold/docker/scripts/generate-world-env.sh

This script will:

1. Read the keys from docker/.env.sui created via the container initialization.
2. Populate the necessary variables in world-contracts/.env

4.2 Example .env

If you need to manually edit or verify the .env files, they should contain the following variables (with actual values filled in):

SUI_NETWORK=localnet
SUI_RPC_URL=http://127.0.0.1:9000

# Use ADMIN_PRIVATE_KEY for GOVERNOR
GOVERNOR_PRIVATE_KEY=<ADMIN_PRIVATE_KEY>
ADMIN_ADDRESS=<ADMIN_ADDRESS>
SPONSOR_ADDRESS=<ADMIN_ADDRESS>

# Private keys for TS scripts
ADMIN_PRIVATE_KEY=<ADMIN_PRIVATE_KEY>
PLAYER_A_PRIVATE_KEY=<PLAYER_A_PRIVATE_KEY>
PLAYER_B_PRIVATE_KEY=<PLAYER_B_PRIVATE_KEY>

TENANT=dev

# Default configs for seeding
FUEL_TYPE_IDS=78437,78515,78516,84868,88319,88335
FUEL_EFFICIENCIES=90,80,40,40,15,10
ASSEMBLY_TYPE_IDS=77917,84556,84955,87119,87120,88063,88064,88067,88068,88069,88070,88071,88082,88083,90184,91978
ENERGY_REQUIRED_VALUES=500,10,950,50,250,100,200,100,200,100,200,300,50,100,1,100
GATE_TYPE_IDS=88086,84955
MAX_DISTANCES=520340175991902420,1040680351983804840

5. Deployment

5.1 Deploy World Package

Inside the container, build and publish the core contracts:

docker exec -it sui-playground /bin/bash

Then, within the container shell:

cd /workspace/world-contracts

Finally deploy the world package:

pnpm install && pnpm deploy-world

Stay in the container for the next steps, if you exit you will need to docker exec -it sui-playground /bin/bash back in to run the configuration and seeding scripts.

5.2 Fix Dependency Resolution (Crucial)

To allow other packages (like builder extensions) to link to your newly published world, Move needs a publication record named Pub.testnet.toml (even on localnet):

mv /workspace/world-contracts/contracts/world/Pub.localnet.toml /workspace/world-contracts/contracts/world/Pub.testnet.toml

5.3 Configure World State

Initialize the global registries and configurations:

pnpm configure-world

6. Spawning Structures (Gate Setup)

Run the automated seeding script to create a working Smart Gate environment:

pnpm create-test-resources

This script performs the following operations:

1. Creates two Character objects.
2. Anchors and fuels a Network Node (NWN).
3. Brings the NWN online.
4. Creates and brings online two Smart Gates.
5. Links the two gates together.

7. Verification

7.1 Check Objects

You can verify the deployment by inspecting the shared objects:

7.1.1 List all objects owned by ADMIN

Import the environment:

source /workspace/builder-scaffold/docker/.env.sui

Then list objects for the admin address:

sui client objects $ADMIN_ADDRESS

7.1.2 Check the status of the Gate

Extract ID from deployments/localnet/extracted-object-ids.json:

GATE_ID=$(cat deployments/localnet/extracted-object-ids.json | jq -r '.world.gateConfig')

Then use this in the next step to check the object:

sui client object $GATE_ID

7.2 Test Jumps

Once the gates are linked and online, you can test the jump functionality:

pnpm tsx ts-scripts/gate/jump.ts

8. Troubleshooting

• “Unpublished dependencies: World”: This means the Pub.testnet.toml file is missing in world-contracts/contracts/world/. Re-run Step 5.2.
• RPC connection refused: Ensure the container is running and port 9000 is mapped. On Linux, if you are running TS scripts from the host, ensure .env uses http://127.0.0.1:9000.
• Faucet Failure: If the container fails to fund accounts on startup, ensure you have an internet connection (the local faucet inside the container is self-contained but initial suiup installation requires it).
• Error: creating container storage: the container name “sui-playground” is already in use by …: This means a container with the name sui-playground already exists. Cleanup the existing container with docker rm sui-playground and try again.
• Error: rootlessport listen tcp 0.0.0.0:9000: bind: address already in use: This means another process is using port 9000 on your host. Stop the process and try again.
• Error: line 47: 57 Illegal instruction (core dumped): This means the Sui binaries are not compatible with your CPU architecture, add platform: linux/amd64 to the sui-dev service in compose.yml to force it to use the correct architecture.

9. Cleanup

To stop and remove the container:

docker stop sui-playground && docker rm sui-playground

To remove the images:

docker rmi docker-sui-dev || docker rmi docker_sui-dev || true

To remove the created volumes:

docker volume rm docker_sui-config

To do a prune of all unused Docker resources (be careful, this will remove all stopped containers, unused networks, dangling images, and build cache):

docker system prune