darkforest-eth/plugins

A showcase of Dark Forest plugins from the community!

Dark Forest Plugins

In v0.5 of Dark Forest, we added the ability to customize the game through "Plugins". These are scripts that are run by the game and provided access to specific aspects of the game.

WARNING

Plugins are evaluated in the context of your game and can access all of your private information (including private key!). Plugins can dynamically load data, which can be switched out from under you!!! Use these plugins at your own risk.

You should not use any plugins that you haven't written yourself or by someone you trust completely. You or someone you trust should control the entire pipeline (such as imported dependencies) and should review plugins before you use them.

Utilities

The Dark Forest in game api has two typical interaction points. In the Dark Forest client you'll find the documentation for the df object and the ui object.

We also provide a series of utilities that plugin authors can use. These are served directly from our website (https://plugins.zkga.me) and you can load them in your plugins. Check out what is available in the javascript directory

If we are missing a utility that would be helpful, feel free to open an issue!

Adding your plugin

You can submit your own plugins by sending a Pull Request to this repository!

You'll need to add your plugin to the content/ directory of this project. Within content/, we have categories, like casual, productivity, or artifacts, please pick the best category, or create a directory for a new one.

Adding a new plugin directory can be done in 2 ways:

1. Install hugo by following https://gohugo.io/getting-started/installing/ then run hugo new CATEGORY/PLUGIN-NAME (where CATEGORY is the category you want and PLUGIN-NAME is the name of your plugin).

2. Copy an already existing plugin directory and rename it to the name of your plugin.

After you've created a new plugin directory, update the index.md, plugin.js, screenshot.png files to fit your plugin. Make sure to add additional information to the comments of the plugin.js that might help other users or developers with your plugin.

Feel free to add additional information to your plugin directory, such as we did with remote-explorer.

Contribution Guidelines

• Comments on top of the script explaining what is is and how to use it
• Has to have screenshot, ideally with result of action and or the ui, should to be ~20kb in size unless you really need more
• Check destructors cleanup all constructors, delete all new, reset all listeners and timers
• Simple clean auditable javascript, expect to go through a little back and forth code review
• No external scripts being loaded except for from us https://plugins.zkga.me/utils/ or a few REALLY big names from knowns cdns have been allowed so far like: https://unpkg.com/htm/preact/standalone.module.js and https://cdn.skypack.dev/lodash.range
• No use of localstorage, overriding internal rpc timers/settings (df.contractsAPI.contractCaller), interaction with or depending on other plugins

Please understand these 'rules' are our best effort to be able to lightly audit code for the protection of the users. Its an impossible job but were trying anyway. If your code doesn't fit in here don't take it personally. The community has also created repos like Awesome Dark Forest which provide no such gatekeeping and are a great way to showcase your work as well.

Reviewer Guidelines

This repo always needs more help reviewing the incoming plugins PRs. Please 'watch' the repo so you get emails of all the new stuff coming in.

Note incoming PRs are obviously not reviewed so you need to be much more careful testing unmerged PRS as they could be malicious. Read the code closely before running, and if possible review untrusted code with a throwaway wallet or local copy of game

Reviewing isn't that big of a task! Anyone can do it

• Is it documented at all?
• Does it work like you'd expect based on documentation?
• Does it work at all, did you test it? report back
• Does it overlap heavily with an existing plugin, or at least say why its different and better than an old one, can you ping the original developer or people who have touched it to give some feedback
• Make sure it follows the contribution and security guidelines
• Think about the general javascript code quality (but don't nitpick too hard)

Leave that feedback in the issue, more than one reviewer is always appreciated

Showcase local development

To develop on the showcase page or theme itself, you can use hugo by installing as per above. You need to checkout the git submodules for the theme with git submodule update --init --recursive and then running hugo server -D in this repository will start a local webserver you can visit with your browser.

plugins's Issues

Smaller map exports result in an empty array

Likely due to chunks consolidation into 1024

Centralize Resources is not working

I am using a ton of the plugins successfully.

Hopefully I am not just being a n00b here but it appears the centralize resources plugin is not working

Just getting a message like this :

Remote Explore is broken

The MinerManager arguments changed

indexedDB instead of localStorage for plugins

I did some research and found out that there is another way to store data on the client side.
We don't want to use localStorage because it contains the private key, but what about indexedDB?

It takes much more code to use it but I tried to make a small code example for people to use:
The 2 functions can be used to load and save one object to the database, inside the object you can put whatever you want (i think). But there is of course a size limit on how much you can store in the DB. The indexedDBName should be different for each plugin.

var indexedDBName = "pluginNameDB";

function loadDataFromIndexedDB() {
	let resolve, reject; let promise = new Promise((res, rej) => { resolve=res; reject=rej; });
	const dbOpen = window.indexedDB.open(indexedDBName, 1);
	dbOpen.onupgradeneeded = (ev) => {
		const db = ev.target.result;
		const store = db.createObjectStore("ObjStore", { keyPath: "id", autoIncrement: true, });
		store.createIndex("Idx", "Idx", { unique: false });
	};
	dbOpen.onsuccess = (ev) => {
		const db = ev.target.result;
		const store = db.transaction("ObjStore", "readonly").objectStore("ObjStore");
		const query = store.get(1);
		query.onerror = (ev) => {
			console.error(indexedDBName+" indexedDB query error", ev.target.error.message);
			reject(ev.target.error.message);
		};
		query.onsuccess = (ev) => {
			db.close();
			if (query.result) {
				resolve(query.result.Idx);
			} else {
				resolve(null);
			}
		};
	};
	return promise;
}

function writeDataToIndexedDB(data) {
	let resolve, reject; let promise = new Promise((res, rej) => { resolve=res; reject=rej; });
	const dbOpen = window.indexedDB.open(indexedDBName, 1);
	dbOpen.onupgradeneeded = (ev) => {
		const db = ev.target.result;
		const store = db.createObjectStore("ObjStore", { keyPath: "id", autoIncrement: true, });
		store.createIndex("Idx", "Idx", { unique: false });
	};
	dbOpen.onsuccess = (ev) => {
		const db = ev.target.result;
		const transaction = db.transaction("ObjStore", "readwrite");
		const store = transaction.objectStore("ObjStore");
		store.put({ id: 1, Idx: data });
		transaction.onerror = (ev) => {
			console.error(indexedDBName+" indexedDB transaction error", ev.target.error.message);
			reject(ev.target.error.message);
		};
		transaction.oncomplete = (ev) => {
			db.close();
			resolve();
		};
	};
	return promise;
}

What do you think? Can this be used?

Player List plugin - feature ideas

This looks good but were going to need to continue to figure out how to not confuse people with the fact that its a list of players YOU CAN SEE. not a global list. For instance on my screen df_dao is #1 score with a total of 5 planets

I agree that this is a problem, i am not sure how to fix it.
Maybe display a message the first time the plugin is started that tells them this information and how the plugin works?
Maybe localStorage could be used to detect if the plugin was first started? It could store the version number of the plugin and when it sees the number does not exist or is lower it will override it and show the information message that explains the plugin.
Is this a good way or bad way of doing it? I never used localStorage

Future requests:
Id also like to a descending order sort on second click maybe, and maybe see an indicator for ascending descending sort and which column is currently being sorted by.

I agree this would be good.
What i also thought about:

• Showing energy growth and silver growth in the list
• Showing artifacts like so: 20/13/7/4/1
  This player has 20 common, 13 rare, 7 epic, 4 legendary, 1 mythic artifact
  The numbers could be in the colors of the artifact rarity.
  The score of the artifacts can be calculated like this:

Common - 5k points
Rare - 20k points
Epic - 200k points
Legendary - 3M points
Mythic - 20M points

This allows to sort by artifact score.

• When clicking on the artifacts of a player a list could pop up that shows the artifacts, the stat boosts, and a button that allows to ui.centerPlanet the planet the artifact is located on.
• When clicking on the planet count of a player it teleports you to their biggest planet (right now it will do that if you click on a players row)
• When hovering over a players row the whole row becomes white / changes color for a visual indication
• When there is an option to click something the mouse turns into an hand and a small text appears that explains what will happen when you click, for example "list artifacts" or "teleport to player"
• Showing voyages in the list for each player: arriving voyages, attacking voyages, incoming attacks
  Could be displayed similar to the artifacts: 5/0/2
  And clicking on them could lead to a list of all voyages and more information about them
• Maybe make a boolean variable for each column in the player list that easily allows you to disable or enable them, so you can make the list smaller and dont show information you dont want to see.

df.getTimeForMove() does not consider worm hole connection

https://github.com/darkforest-eth/client/blob/master/docs/classes/backend_gamelogic_gamemanager.default.md#gettimeformove

It will ignore the worm hole connection and return the wrong time.
I did not test it with photon cannons, might also return the wrong time.

Plugins for observers/casters

This is a catch-all issue for things people want as plugins useful when observing or "casting" a game.

From Jordan:

• Creating flags or areas of note on top of the map to go back and see them later #128
• Player selector: Check boxes to see what players' planets you want to see at any given time. (Helps to reduce the noise if 2 players are fighting and a couple other players are around them too but you dont want to see them)
• More options for reducing planet clutter
• Be able to change player colors
• Be able to watch multiple places at once (picture in picture? split up the main map into 4 small maps each with independent viewports?)

Gift planet/Empire requires lowercase addresses

We should probably just lowercase the string always.

getPlanetsInRange() - faster

I wrote my own very simple function to get planets in range and compared it to the default one,
The custom simple one is 3-4 faster, but maybe its not as good somehow? maybe i did something wrong

function getRange(planet, percentEnergySending = 100) {
    if (percentEnergySending === 0) return 0;
    return Math.max(Math.log2(percentEnergySending / 5), 0) * planet.range;
}
function getDistance(p1, p2) {
    let x = p2.location.coords.x - p1.location.coords.x;
    let y = p2.location.coords.y - p1.location.coords.y;
    return Math.sqrt(x*x + y*y);
}
function perfTest() {
    var planetId = "*put your planet id here*";
    var planet = df.getPlanetWithId(planetId);

    let ds = new Date();
    let l = df.getPlanetsInRange(planetId);
    let de = new Date();
    console.log("planetCount: "+l.length+" time: "+(de.getTime()-ds.getTime()))

    let xs = new Date();
    let allPlanets = df.getAllPlanets();
    let arr = [];
    let range = getRange(planet);
    for (var p of allPlanets) {
        if (!p.location) continue;
        if (!p.location.coords) continue;
        if (getDistance(planet, p) < range)
            arr.push(p);
    }
    let xe = new Date();
    console.log("planetCount: "+arr.length+" time: "+(xe.getTime()-xs.getTime()))
}
perfTest();

output:

planetCount: 16804 time: 54
planetCount: 16804 time: 17

queued-move.js gas price is static

queued-move.js needs to be updated to match the chosen gas price in settings instead of just using the default 1 gwei hard coded in the file.

This could fix issues with other plugins that rely on that resource for sends.

Improvements of existing plugins

After using most of them a while I have some concerns on which I will work in free time, but anyone can too :)

Here is my list:

Estimate travel time

• update core to show H:M:S OR plugin to show correct amount of time
  example: I did this change in my plugin as we see attacks in seconds ONLY right now:
  

Distribute resources

• do not use quasars
• use only asteroids option
• prioritize black holes first (send to it) if checkbox

Center resources

• do not use quasars

Quick upgrade

• define area of where it will work

Crawler

• set max. level planets to use
• do not use quasars
• ability to define area where crawl works (not whole empire)
• set min. level planets to use??

Highlight artifact

• upgrade to 0.6

Besides that I have some ideas on new plugins on which I will work in free time.
Cheers and stay strong!

Replace icons with @darkforest_eth/ui

I vendored Icons as https://github.com/darkforest-eth/plugins/blob/master/javascript/game/Icons.js but the core team now provides the Icons as a CustomElement in https://github.com/darkforest-eth/packages/tree/master/ui

The vendored icons need to be replaced with the new components.

Plugin windows act weird when area is offscreen

Example:
Take a plugin window (any plugin) and minimize it.
Now move it to the bottom of the screen and maximize it again.
Its area should now be off-screen.
If you now click the window anywhere (even close button) it will not react to the click but instead position itself upwards so its area is again on the screen.

Suggestions:

• Only reposition plugin on click when its title bar is off-screen
  (this way people can move it onscreen themselves and can have it off-screen on purpose if they don't want to see the whole plugin)
• If a plugin gets maximized automatically move its area on-screen (if possible), but also remember how it was when minimized so when you minimize it again it will move back to the minimized position.

If a plugin window grows too big, parts of it will spawn off-screen. (for example Player List - if you have many players on your map)
Is there a way to position your plugin somehow with code?
Or to make it so it will move on-screen again automatically?