|
| 1 | +# ConfigAPI |
| 2 | +Config API for Bukkit 1.8 - 1.16 based on Dynamic Proxies |
| 3 | + |
| 4 | +## Features: |
| 5 | + - Create config via Interface with `default` getters and setters |
| 6 | + - Automatic generation of YAML files based on Java code |
| 7 | + - Automatic updates of YAML file after adding new field to config |
| 8 | + - Support of comments in YAML files |
| 9 | + - Support of multiple config files |
| 10 | + - System of serializers for custom objects (e.g. ItemStack, Location) |
| 11 | + - Automatic translation of `&` based colors |
| 12 | + |
| 13 | +## Import |
| 14 | +#### Gradle |
| 15 | +```groovy |
| 16 | +maven { |
| 17 | + url = 'https://repo.mikigal.pl/releases' |
| 18 | +} |
| 19 | +
|
| 20 | +compile group: 'pl.mikigal', name: 'ConfigAPI', version: '1.0' |
| 21 | +``` |
| 22 | + |
| 23 | +#### Maven |
| 24 | +```xml |
| 25 | +<repository> |
| 26 | + <id>mikigal-repo</id> |
| 27 | + <url>https://repo.mikigal.pl/releases</url> |
| 28 | +</repository> |
| 29 | + |
| 30 | +<dependency> |
| 31 | + <groupId>pl.mikigal</groupId> |
| 32 | + <artifactId>ConfigAPI</artifactId> |
| 33 | + <version>1.0</version> |
| 34 | + <scope>compile</scope> |
| 35 | +</dependency> |
| 36 | +``` |
| 37 | + |
| 38 | +## How to use? |
| 39 | +#### Java code |
| 40 | +```java |
| 41 | +public class TestPlugin extends JavaPlugin { |
| 42 | + |
| 43 | + private static TestConfig testConfig; |
| 44 | + |
| 45 | + @Override |
| 46 | + public void onEnable() { |
| 47 | + testConfig = ConfigAPI.init( |
| 48 | + TestConfig.class, // Class of config's interface |
| 49 | + NameStyle.UNDERSCORE, // Style of fields' name in YAML file |
| 50 | + CommentStyle.INLINE, // Style of comments in YAML file |
| 51 | + true, // Automatic translation of '&' based colors |
| 52 | + this // Instance of plugin |
| 53 | + ); |
| 54 | + |
| 55 | + // You can simply access data from the config by getters |
| 56 | + System.out.println(testConfig.getExampleMessage()); |
| 57 | + Bukkit.getPlayer("mikigal").getInventory().addItem(testConfig.getAward()); |
| 58 | + |
| 59 | + // After calling setter new data are automatically saved to file |
| 60 | + testConfig.setAward(new ItemStack(Material.DIRT)); |
| 61 | + |
| 62 | + // If you want to do something manually you can access instance of YamlConfiguration |
| 63 | + testConfig.getBukkitConfiguration(); |
| 64 | + } |
| 65 | + |
| 66 | + public static TestConfig getTestConfig() { |
| 67 | + return testConfig; |
| 68 | + } |
| 69 | +} |
| 70 | + |
| 71 | +@ConfigName("test.yml") // Name of YAML file |
| 72 | +public interface TestConfig extends Config { |
| 73 | + |
| 74 | + @Comment("This comment will be saved to YAML file!") |
| 75 | + default String getExampleMessage() { |
| 76 | + // Getter method should return default value of the field |
| 77 | + return "&cIt's default value of example message"; |
| 78 | + } |
| 79 | + |
| 80 | + default ItemStack getAward() { |
| 81 | + return Item.of(Material.DIAMOND_SWORD) |
| 82 | + .name("&cAward") |
| 83 | + .lore("&aFirst line", "&cSecond line") |
| 84 | + .toItem(); |
| 85 | + } |
| 86 | + |
| 87 | + public void setAward(ItemStack award); |
| 88 | + |
| 89 | + // Key of Map must be String |
| 90 | + default Map<String, Integer> getValues() { |
| 91 | + Map<String, Integer> map = new HashMap<>(); |
| 92 | + map.put("a", 1); |
| 93 | + map.put("b", 2); |
| 94 | + |
| 95 | + return map; |
| 96 | + } |
| 97 | + |
| 98 | + default List<Location> getSpawnPoints() { |
| 99 | + World world = Bukkit.getWorld("world"); |
| 100 | + return Arrays.asList( |
| 101 | + new Location(world, 0, 100, 0), |
| 102 | + new Location(world, 10, 90, 10, 90f, 0f), |
| 103 | + new Location(world, 20, 80, 20, 0f, 180f) |
| 104 | + ); |
| 105 | + } |
| 106 | +} |
| 107 | +``` |
| 108 | + |
| 109 | +#### Automatic generated YAML from above Java code |
| 110 | +```yaml |
| 111 | +values: |
| 112 | + a: 1 |
| 113 | + b: 2 |
| 114 | +example_message: '&cIt''s default value of example message' # This comment will be saved to YAML file! |
| 115 | +spawn_points: |
| 116 | + type: org.bukkit.Location |
| 117 | + '0': |
| 118 | + world: world |
| 119 | + x: 0.0 |
| 120 | + y: 100.0 |
| 121 | + z: 0.0 |
| 122 | + yaw: 0.0 |
| 123 | + pitch: 0.0 |
| 124 | + '1': |
| 125 | + world: world |
| 126 | + x: 10.0 |
| 127 | + y: 90.0 |
| 128 | + z: 10.0 |
| 129 | + yaw: 90.0 |
| 130 | + pitch: 0.0 |
| 131 | + '2': |
| 132 | + world: world |
| 133 | + x: 20.0 |
| 134 | + y: 80.0 |
| 135 | + z: 20.0 |
| 136 | + yaw: 0.0 |
| 137 | + pitch: 180.0 |
| 138 | +award: |
| 139 | + material: DIAMOND_SWORD |
| 140 | + amount: 1 |
| 141 | + name: '&cAward' |
| 142 | + lore: |
| 143 | + - '&aFirst line' |
| 144 | + - '&cSecond line' |
| 145 | + |
| 146 | +``` |
| 147 | + |
| 148 | +## Serializers |
| 149 | +### API has built-in serializers for: |
| 150 | + - ItemStack |
| 151 | + - Location |
| 152 | + - PotionEffect |
| 153 | + - ShapedRecipe |
| 154 | + - UUID |
| 155 | + |
| 156 | +#### You can also make your own serializers |
| 157 | +```java |
| 158 | +public class PotionEffectSerializer extends Serializer<PotionEffect> { |
| 159 | + |
| 160 | + @Override |
| 161 | + protected void saveObject(String path, PotionEffect object, BukkitConfiguration configuration) { |
| 162 | + // In saveObject() method you have to set data of object to config. You can use set() method to set another object which need serialization too |
| 163 | + configuration.set(path + ".type", object.getType().getName()); |
| 164 | + configuration.set(path + ".duration", object.getDuration()); |
| 165 | + configuration.set(path + ".amplifier", object.getAmplifier()); |
| 166 | + } |
| 167 | + |
| 168 | + @Override |
| 169 | + public PotionEffect deserialize(String path, BukkitConfiguration configuration) { |
| 170 | + // In deserialize() method you have to load data from config and return instance of object |
| 171 | + PotionEffectType type = PotionEffectType.getByName(configuration.getString(path + ".type")); |
| 172 | + int duration = configuration.getInt(path + ".duration"); |
| 173 | + int amplifier = configuration.getInt(path + ".amplifier"); |
| 174 | + |
| 175 | + if (type == null) { |
| 176 | + throw new InvalidConfigFileException("Invalid PotionEffect type (path: " + path + ")"); |
| 177 | + } |
| 178 | + |
| 179 | + return new PotionEffect(type, duration, amplifier); |
| 180 | + } |
| 181 | +} |
| 182 | + |
| 183 | +public class TestPlugin extends JavaPlugin { |
| 184 | + |
| 185 | + @Override |
| 186 | + public void onEnable() { |
| 187 | + // Remember to register you Serializer before use! |
| 188 | + ConfigAPI.registerSerializer(PotionEffect.class, new PotionEffectSerializer()); |
| 189 | + |
| 190 | + // Init your configs... |
| 191 | + |
| 192 | + } |
| 193 | +} |
0 commit comments