Skip to content

Discord bot setup

Jump to bottom
berichan edited this page Oct 21, 2024 · 34 revisions

Prerequisits

You must have the following to run a copy of this bot:

  • A custom-firmware capable switch running Atmosphere in sysnand that isn't banned. DO NOT USE EMUNAND!
  • A legitimate copy of ACNH (either digital or cart)

Details

Please note that the setup to this bot is much different to other sysbots, and migrating will require you to move both the config.json and anchors.bin file.

You must setup the bot normally even if you are only using the automated/dodo-restore functionality of the bot.

How this bot works per order:

  1. Restart the game if this is the first order or the last order faulted. This is the most reliable way to do this if running endlessly atm, and the bot is designed to work full automated without any input from the host.
  2. Wait for Isabelle's speech (if any), Notify player to be ready, teleport player into their airport then in front of orville (or start here if the last order was a success), open gate & inform dodo code.
  3. Notify player to come now, teleport outside into drop zone. Once the player arrives, wait for them to leave (or close and restart if they fail to show up in the allocated time)
  4. Once the timer runs out or the user leaves, close the gate and start over with next user in the queue.

To use this bot, you must be using a save that:

  1. Does not have a nook miles ticket in the inventory
  2. Only has one player living on the island
  3. Has used up the nook miles ticket you get for free from Tom Nook
  4. Has already gone through the "legal eagles" talk with Orville for online play, and
  5. Has the airport, house, and the map spawn location as close to each-other as possible.

Parts of this guide are liberally adapted from SysBot.AnimalCrossing by kwsch.

I would also like to credit to Glaze for the amazing documentation upkeep he does.

Setup

Create a new Discord Application and Bot for your server on Discord's Developer Portal.

To invite the Bot to your server, you must generate an OAuth2 URL with the correct permissions. Click on the OAuth2 tab in the sidebar, select bot under "Scopes," and grant your bot permissions. You will need at minimum:

  • Send Messages
  • Read Message History
  • Manage Messages
  • Embed Links (for the neat embeds such as in $info.)

Optionally

  • Add Reactions
  • Use External Emojis

Under the Bot tab, make your bot private to prevent other people from inviting it to their servers and using your Switch.

  • Enable Privileged Gateway Intents, Server Members Intent and Message Content Intent under the same tab.

Before Starting

When you start the application by clicking the .exe, the Discord bot will be launched.

Configure the bot's settings on your server. If you only want it in a few specific channels, remove all the permissions on the bot's role itself and add the role to specific channels only. Ensure that you do not have any other roles that are restricting the bot's permissions (including the "everyone" role), and you enter any extra codes needed if you have 2FA enabled.

NOTE: You will need to restart the .exe for changes to take affect, after restarting you will also need to set the dodo code again.

Configuration Setup

Install sys-botbase and ldn-mitm to your switch running atmosphere if you haven't done already. Both of these are required to run this program.

Download and unzip ACNH.SysBotOrders to your computer.

Run the SysBot.ACNHOrders.exe file in the SysBot-ACNH-Orders folder

This will create an empty config.json which you will need to fill out. Most of the fields are self-explanatory, and are explained in the SysBot.AnimalCrossing repo at the top of this page. I'll summarize the few you need to change here:

Main:

  • Name: The name of your bot, seperate from the username and nickname your bot has in Discord.
    • This will also display in the playing status of your bot. It will say Playing followed by whatever you changed this variable to.
  • Token: The token of your Discord application, to request a token go to Discord's Developer Portal.
    • Do not share this token with other people, as it will allow them to run their own code on your bot account.
  • Prefix: Character before your message that indicates it's a command.
    • Default is $.
  • RoleUseBot: Name of the role required to use bot commands other than $help and $info.
    • Leaving this as the default @everyone will make it so no role is required.
  • Channels: List of channel IDs in which commands may be used.
    • Leaving this empty causes commands to be usable in any channel.
  • Users: List of user IDs that are allowed to use commands.
    • Leaving this empty causes anyone to be able to use commands. Alternatively, just setup using RoleUseBot above.
  • Sudo: List of user IDs that are granted sudo access, allowing them to use commands in the Control Module.
  • LoggingChannels: List of discord channel IDs where you want verbose bot logging.

OrderConfig:

  • MaxQueueCount: The maximum number of people the bot will queue before it stops accepting new users.
    • This is a slow bot, 99 people in the queue would take ~8 hours to run down, so this is the internal hard limit.
  • UserTimeAllowed: How long the player is allowed to stay on your island before they are booted.
    • Somewhere between 150 - 200 seconds should be fine. If you want people to rush then you may set this as low as 120 seconds.
  • WaitForArriverTime: How long the bot will wait for the player to start arriving before their order is cancelled.
    • Somewhere between 60 - 90 seconds is good. The bot will tell the player to clean their inventory and wait on the dodo code screen when starting.
  • ArrivalTime: The amount of time it takes for someone to arrive at your island.
    • This will depend on both your's and the other player's connection. Leave it at 60 seconds if you don't want to time it.
  • CompleteOrderMessage: What to send the player once they leave the island. Pick something cute, don't be mean.
    • Or do be mean, I'm a wiki, not a cop.
  • RetryFetchDodoOnFail: Whether or not to retry fetching the dodo code if the first try fails.
    • Set this to true if your connection isn't perfect.
  • ShowIDs: Whether or not you would like to include IDs in the echos and order replies.
  • PingOnAbuseDetection: Should the bot ping the bot owner when it detects an alt account?
  • PenaltyBanCount: Set this to a number higher than 0 if you want to softban people for not arriving/leaving on time. This must be above 0 to use the ban command
  • PositionCommandCooldown: How many seconds a user has to wait to use the $qs/$position commands
  • NHIPresetsDirectory: Folder of presets that can be ordered using $preset [filename]
  • EchoArrivingLeavingChannels: Channel IDs separated by a comma where you'd like to echo arrival and leaving events of orderers.

The WrapAllItems and WrappingPaper values will be ignored in the OrderConfig part of the config, leave them as-is.

Main (again):

  • AllowLookup: Set this to true if you just want to allow users to call the $lookup and customize commands.
  • DodoRestoreConfig: See Dodo restoration, this will turn off the order functionality of the application.
  • ForceUpdateAnchors: Set this to true if you just want to update the anchors (covered below) without running the actual bot.
  • MapPlaceX/Y This is where your items will be injected for the order, try to make them as close to the airport as possible.
    • Use either ACNHMobileSpawner or NHSE to find good co-ordinates. Here's an example co-ordinate using the map editor in ACNHMobileSpawner:
  • MapPullChunkSize How much of the map to pull over the network at a time. Set this to a lower amount if you are experiencing atmosphere crashes
    • The maximum value for this is 8192, which will give you the fastest map injection functionality.
  • DeleteNonCommands: If Channels is populated, should anything invalid (such as general conversation) be removed? Does not apply to sudo
  • DialogueButtonPressExtraDelay: Extra time to wait between dodo talk keypresses in milliseconds
  • RestartGameWait: Extra time in milliseconds to wait before game gets restarted.
    • Possibly useful if you have to wait for the "checking if game can be played" wheel
  • ExtraTimeConnectionWait: How much extra time, if any, should we wait while orville is connecting to the internet (in milliseconds)
  • LegacyDodoCodeRetrieval: Set this to true if the instant text loop keeps trying to open the gates via local play
    • All button presses will be much slower.
  • ExperimentalFreezeDodoCodeRetrieval: Should we freeze instant text and send the entire dodo fetch as one command? (requires sys-botbase >= 1.72)
    • Will not work alongside third party refresh functions (will work fine with freeze on the built-in refresh)
  • ExperimentalSleepScreenOnIdle: Should we sleep the screen when not doing anything? (requires sys-botbase >= 1.72)
  • AllowVillagerInjection: Set this to true if you want to allow villager injections or order attachments.
  • HideArrivalNames: Should we blank out island and arrival names on the arrivals screen?
  • BlockerEmoji: Character to use to be placed over the dodo and arrival names.
    • Written to blocker.txt and to be used as a text source in streaming software.
  • FieldLayerNHLDirectory: NHL directory to be used by $loadLayer
    • Place .nhl files created by ACNHMS or NHSE in this directory and load them when refreshing using the built-in refresher.
  • AllowKnownAbusers: Should we allow known hackers/abusers from using the order bot? (community-built list)
  • AvoidSystemUpdate: Should we press up once before starting the game? Not guaranteed to avoid the update, but the bot will try its best.
  • SignalrConfig: If you have a web server that accepts SignalR requests, the bot can send dodo code updates to your server.
    • It's up to you to create the server. Relevant classes for your client are in the source's Signalr folder
  • IP: The IP that should be connected to.
    • You can find this by going to the Homebrew Menu on your Switch and pressing Y.
  • Port: Port the bot will try to connect to, do not change this.

Game Setup

Turn on your console, open up animal crossing to the point where you've just exited your house (don't move at all!) then run the SysBot.ACNHOrders.exe again.

These next few steps will create "anchors" which are places your player will teleport to for the bot functionality to work. There are 5 of these anchors you need to set and it should take about 5 minutes if you get them right the first time:

To set an anchor, a sudo user on discord (or the bot owner) will need to do use following commands:

  • $setAnchor: To set that as the anchor for that position.
  • $loadAnchor: To load that anchor (should only be used for debugging to see if you've set the anchor correctly.)

Ensure your gates are CLOSED before attempting to load or set anchors.

0: HouseEntryAnchor

Set this anchor immediately when your player exits the house on start up. Any movement at all will cause this anchor to corrupt, so ensure you don't have joy-con drift or have moved even a little from your starting position. The command to set the anchor is $setanchor 0 and test with $loadanchor 0 Example

1: DropPositionAnchor

Set this anchor somewhere close to the airport, this is where your player will wait for the duration of the other player's pickup. The other user may use SysBot.AnimalCrossing-style drop commands or drop commands created with ACNHMobileSpawner just incase they've forgotten anything here, so ensure there is space for the drop. The command to set the anchor is $setanchor 1 and test with $loadanchor 1 Example

2: AirportEntryAnchor

Set this anchor diagonally facing the airport entry door. The command to set the anchor is $setanchor 2 and test with $loadanchor 2 Example

3: OrvilleTalkAnchor

Set this anchor in front of Orville, the dodo, at the airport. The command to set the anchor is $setanchor 3 and test with $loadanchor 3 Example

4: AirportExitAnchor

Set this anchor at the airport facing the exit door. The command to set the anchor is $setanchor 4 and test with $loadanchor 4 Example

Villagers

Your users may request villagers by attaching villager:{id} to the end of their order command, this functionality is only available if you have AllowVillagerInjection set to true in your config. Please note that villagers will be injected to the first slot (0) of your save, so try to keep this house as close to the order drop zone as possible.

For example, to order nook miles tickets and have raymond waiting for you on the island to take him, your order command would be $order nook miles ticket villager:cat23

Testing

You can order an item using $order or using the catalogue functionality of ACNHMobileSpawner.

There are two types of order loops:

  1. The "long" loop. This one restarts the game before starting the order functions. The first order will require this as well as orders after a fault/no-arrival.
  2. The "shorter" loop. After a successfull order, the bot will wait at Orville, then begin the order functions.

Please see this video for how the bot should behave, as well as the order wiki page.

Clone this wiki locally