Geoffrey-Django/GeoffreyApp/docs/source/getting_started.rst

.. _getting_started:

Getting Started
***************

What is a Geoffrey?
-------------------

Geoffrey is a database for storing information on locations, shops, item listings, farms, etc for Minecraft servers.
It can help you find someone's base, a shop selling an item you need, and much more!

Information in Geoffrey can be accessed in server ways:

* In-Game through the `Geoffrey Plugin <https://git.canopymc.net/Geoffrey/Geoffrey-MC-Plugin>`__
* Via Discord using the `Geoffrey Bot <https://git.canopymc.net/Geoffrey/Geoffrey-Bot>`__
* Online via the `Geoffrey Django App <https://git.canopymc.net/Geoffrey/Geoffrey-Django>`__

.. note::

    To see all commands for Geoffrey use ``?help`` in Discord or ``/help geoffrey`` in game!

Types of Locations
------------------

Locations are places you can visit in-game. There are several kinds in Geoffrey:

* Bases: Basic location for marking where you live
* Shops: A location that can sell items
* Towns: For group builds where multiple people living at a single location
* Markets: A collection of shops
* Public Farms: Locations that produces a resource
* Attractions: Fun locations for minigames, parkour, gambling, etc

Registering
-----------

Before you can add things to Geoffrey, you must register.

* In Discord: ``?register``
* In Game: ``/register``

This allows Geoffrey to link to your MC account.

Searching in The Database
-------------------------

Finding a Location Or Player
++++++++++++++++++++++++++++

The ``find`` command is used to find bases and shops in Geoffrey. ``find`` searches for both location names and owner names:

* In Discord: ``?find <Query>``
* In Game: ``/find <Query>``

Getting More Info on A Location
+++++++++++++++++++++++++++++++

Then to find out more info about a location, use ``info``:

* In Discord: ``?info <Location Name>``
* In Game: ``/info <Location Name>``

Finding Items For Sale
++++++++++++++++++++++

``selling`` can be used to find items for sale.

.. note::

    It is better to search for a sub-string of an item name. Example: for ``enderchests`` search ``ender``

* In Discord: ``?selling <Item Name>``
* In Game: ``/selling <Item Name>``

Finding Locations Around A Point
++++++++++++++++++++++++++++++++

You can also search around a position for locations with ``find_around``:

* In Discord: ``?find_around <X> <Y>``
* In Game: ``/find_around <X> <Y>``

Creating Locations
------------------

To add a location, you need to use one of the ``add`` commands. Each location type has its own command. For example to,
 add a base you use ``add_base``:

* In Discord: ``?add_base <X> <Y> <Optional Name>``
* In Game: ``/add_base <Optional Name>`` (your current location is used)

Example::

    ?add_base 500 -500 Cool Base 123
    /add_base Cool Base 123

.. note::

    If a name is not provided, the name defaults to ``[Username]'s [Location Type]``

Adding A Nether Tunnel
++++++++++++++++++++++

Locations can also have a nether tunnel associated with them:

* In Discord: ``?add_tunnel <Tunnel Direction> <Tunnel Number> <Location Name>``
* In Game: ``/add_tunnel <Tunnel Direction> <Tunnel Number> <Location Name>``

Example::

    ?add_tunnel North 155 Cool Base 123
    /add_tunnel North 155 Cool Base 123

Shops
-----

Creating
++++++++

A shop can be added like a base:

* In Discord: ``?add_shop <X> <Y> <Optional Name>``
* In Game: ``/add_shop <Optional Name>`` (your current location is used)

Listing An Item For Sale
++++++++++++++++++++++++

With the shop created, you can then add then items for sale:

* In Discord: ``?add_item <Item Name> <Quantity> <Diamond Price> <Shop Name>``
* In Game: ``/add_item <Item Name> <Quantity> <Diamond Price> <Shop Name>```

Example of adding a listing for one stack of dirt costing 1 Diamond::

    ?add_item dirt 64 1 Cool Shop 123
    /add_item dirt 64 1 Cool Shop 123

Restocking Items
++++++++++++++++

The ``selling`` command places items that have been stocked more recently at the top of its results. To restock an item,
you can use the ``restock`` command. This will make sure your listing gets put at the top (for now...):

* In Discord: ``?restock <Item Name> <Shop Name>``
* In Game: ``/restock <Item Name> <Shop Name>``

Example::

    ?restock dirt Cool Shop 123
    /restock dirt Cool Shop 123

.. note::
    You can use Regex to match multiple names and restock many items at once. Example: ``?restock diamond.*`` restocks
    all items that begin with ``diamond``

Removing Item Listings
++++++++++++++++++++++

If you want to delete an item, you use the ``delete_item`` command:

* In Discord: ``?delete_item <Item Name> <Shop Name>``
* In Game: ``/delete_item <Item Name> <Shop Name>``

Example::

    ?delete_item dirt Cool Shop 123
    /delete_item dirt Cool Shop 123

Towns
-----

Towns are essentially bases that can have multiple residents.

Creating
++++++++

A town can be added like any other location:

* In Discord: ``?add_town <X> <Y> <Optional Name>``
* In Game: ``/add_town <Optional Name>`` (your current location is used)

Adding Residents
++++++++++++++++

Adding residents can be done with ``add_resident``:

* In Discord: ``?add_resident <Resident Username> <Town Name>``
* In Game: ``/add_resident <Resident Username> <Town Name>``

.. note::

    The resident being added must be registered with Geoffrey!

Removing Residents
++++++++++++++++++

Someone has left your town? You can remove them using ``remove_resident``:

* In Discord: ``?remove_resident <Resident Username> <Town Name>``
* In Game: ``/remove_resident <Resident Username> <Town Name>``


Editing Locations
-----------------

Renaming
++++++++

To rename a location, use ``edit_name``:

* In Discord: ``?edit_name "<New Name>" "<Old Name>"``
* In Game: ``/edit_name "<New Name>" "<Old Name>"``

.. warning::
    You must put quotes (``" "``) around both the new name and the old name

Moving A Location
+++++++++++++++++

You can move a location with ``edit_pos``:

* In Discord: ``?edit_pos <X> <Y> <Location Name>``
* In Game: ``/edit_pos <X> <Y> <Location Name>``

Editing a Tunnel
++++++++++++++++

To change the tunnel of a base, use ``?edit_tunnel``:

* In Discord: ``?edit_tunnel <Tunnel Direction> <Tunnel Number> <Location Name>``
* In Game: ``/edit_tunnel <Tunnel Direction> <Tunnel Number> <Location Name>``

Deleting a Location
+++++++++++++++++++

Things change, and sometimes locations need to be *removed*... you do this using ``delete``:

* In Discord: ``?delete <Location Name>``
* In Game: ``/delete <Location Name>``

Now What?
---------

Make sure to use ``?help`` in Discord or ``/help geoffrey`` in-game to see everything Geoffrey can do!