README.md

EarthMC-Wrapper

An unofficial Java API wrapper/client to interact with the EarthMC Map and Official API.

Installation

• Authenticate with GitHub Packages

1. Head to Account -> Developer Settings -> Personal Access Token (classic) -> Generate New Token.

2. Give it any name and the appropriate repository permissions, then hit Generate.

3. On your machine, create two new system environment variables:

   Name: USERNAME
   Value: yourGitHubUsername

   Name: GITHUB_TOKEN
   Value: yourTokenHere
   

• Add package dependency to build file.

  build.gradle

  repositories {
      maven {
          url = uri("https://maven.pkg.github.com/earthmc-toolkit/earthmc-wrapper")
          credentials {
              username = System.getenv("USERNAME")
              password = System.getenv("GITHUB_TOKEN")
          }
      }
  }
  
  dependencies {
    // NOTE: This may not be up-to-date! Make sure to replace this version with the latest.
    api 'io.github.emcw:emc-wrapper:1.0.1'
  }

Basic Example

import io.github.emcw.EMCWrapper; // The main wrapper for registering and retreiving map instances.
import io.github.emcw.KnownMap; // Enum containing all map names that EMCW is aware of.
import io.github.emcw.Squaremap; // The map type, important to parsing data correctly. Other maps are not currently needed.

import io.github.emcw.squaremap.entities.*;

public class Main {
    static final EMCWrapper emcw = new EMCWrapper()
        .registerSquaremap(KnownMap.AURORA); // Map names are unique. Registering the same one more than once has no effect.

     // Gets the map from the registry as the type we registered as.
    static final Squaremap auroraMap = emcw.getSquaremap(KnownMap.AURORA);

    // Allows us to interact with the OAPI for a specific map. Supports custom calls via `sendRequest`.
    static final OfficialAPI.V3 auroraAPI = new OfficialAPI.V3(KnownMap.AURORA);

    public static void main(String[] args) {
        // Use data from the Official API.
        System.out.println(auroraAPI.serverInfo());

        // Use data from the map
        Map<String, SquaremapTown> all = auroraMap.Towns.getAll();
        System.out.println(all.size());

        Map<String, SquaremapOnlinePlayer> townless = auroraMap.Players.getByResidency(false);
        System.out.println(townless.keySet());

        Map<String, SquaremapOnlineResident> onlineResidents = auroraMap.Residents.getOnline();
        System.out.println(residents.get("Owen3H").getLocation());
    }
}

Documentation

You currently won't see much embedded documentation as you are using EMCW. However, I plan to gradually document new and existing fields, methods & classes to give more context. For now, the syntax should be closely similar to the NPM Package although wrapper/map initialization may slightly differ.

Visit the Javadoc page.

Note

Since this library uses Lombok, it is most likely that fields you try to access are private, though public getters are provided.

// Example EMCW class
public class Nation {
    @Getter String leader;
}

// Usage
public class Test {
    public static void main(String[] args) {
        SquaremapNation exampleNation = Aurora.Nations.getSingle("nationName");

        // Here we can see Lombok in use.
        String leader = exampleNation.leader; // Does not work
        String leader = exampleNation.getLeader(); // Works
   }
}

Map Classes

• All map classes inherit the following methods:
  • .getAll() - Retrieve the entire map of entities.
  • .getSingle("name") - Retrieve a single entity by its name.
  • .getMultiple("name", "anotherName") - Returns a list of entities by inputting their names.

Towns

Nations

Residents

Players