Super-DuckHunt Help & Resources

--------------------------------------------------------------
1. Setting up the bot
--------------------------------------------------------------

This bot requires Python version 3.12.0 to be installed on the running machine.

Anytime you wish to change the bot's username, password, server, port or channel, it must be done manually following this process.

If you're setting up, place all files in the same folder.
REQUIRED FILES: main.py bot.py, duckhunt.cnf [Also: func.py in v1.0.0 to v1.1.3-2]
NOTE: As of version 1.1.4 func.py has been integrated into bot.py and main.py and is no longer needed or included.

Don't run the bot yet. (Shut it down, if it is running)

Open duckhunt.cnf with a text editor

At the top, under section [duckhunt]
" server = " input the server being used.
" port = " For regular connection input 6667 (Version 1.1.0 to 1.1.3), for SSL use 6697 (Version 1.1.3-2+)
" botname = DuckHunt "can be DuckHunt or whatever you choose (case sensative)
" botpass = 0 " is optional, set as 0 if not used. (case sensative)
" duckchan = #duckhunt " is the bot channel. NO CAPS MUST BE ALL LOWER CASE: #channel. duckchan can be #duckhunt or whatever you choose. 1 CHANNEL ONLY
" botmaster = YourUsername " this gives you full bot master control of the bot. REQUIRED.
" admin = 0 " to clear admin list. Leave as 0 do not manually input admins.
" botignore = 0 " to clear ignore list. Leave as 0 do not manually input ignores.
" serverssl = " (Version 1.1.32+) 'off' if using port non-SSL, 'on' if using SSL (see SSL Option below)
[duckhunt]
server = irc.yourservername.net
port = 6667
botname = DuckHunt
botpass = password
duckchan = #duckhunt
botmaster = YourUsername
admin = 0
ignore = 0
serverssl = off

SSL Option v1.1.3-2+

Versions 1.1.3-2 and higher can connect to IRC networks that support SSL/TLS! If you are using versions 1.1.0 to 1.1.3 SSL option is NOT AVAILABLE.
If you wish to use SSL, in duckhunt.cnf (described above), in [duckhunt] use port = 6697, and add/set serverssl = on

[duckhunt]
...
port = 6697
...
serverssl = on

Do not manually alter any other settings in the file. The bot has built in configuration commands. (See configuration). The above list of items may not appear in the same order in duckhunt.cnf. Check only section [duckhunt] for these items. More information on duckhunt.cnf will be available in the up coming Modifier's Guide.

Save duckhunt.cnf and close the file.

Run the bot from main.py (python3 main.py)

--------------------------------------------------------------
2. Configuration
--------------------------------------------------------------

This bot comes pre-configured with a default configuration. Once you have completed Section 1,(Setting up the bot), the bot is ready to go and will begin its process once it joins the specified server and chat.

!duckhunt on

!duckhunt off

FURTHER CONFIGURATION IS USER DEFINED.

If you need to restore your duckhunt.cnf to pre-configuration settings

please view the Bot Maintenance and Reset Functions.

This bot has the ability to change the configuration and settings live, while the bot is running. There is no need to configure or change settings of this bot thru duckhunt.cnf file, and the bot will not need to be restarted. All changes take effect immediately.

[Configuration Explanation]

The configuration commands can only be used by botmasters. The configuration of this bot is stored in the duckhunt.cnf file. This bot has the capability to make live changes to its configuration, and making the changes take effect quickly, if not immediately. More information on duckhunt.cnf will be available in the Modifier's Guide

Everything works based on time, random numbers and percentages that are set within a specified range. The various values and settings that can be configured in this bot allow each botmaster to fine tune their DuckHunt bots for their chats.

PLEASE NOTE: The Help Documentation is designed to follow the stock (or pre-configured) settings. Making your own changes may cause game experience to change, based on the settings you declare. Some commands or game situations may be enabled or disabled per botmaster definition.

[Core Configuration]

Core configuration values are: maxducks, spawntime, flytime, duckexp, duckfear, duckgold, friendrate

The following commands will change these values. (Pre-configured values listed)

maxducks

/msg botname set maxducks X

maxducks is the maximum amount of ducks that can exist at once; Recommend 3-6.
Pre-config: 6

spawntime

/msg botname set spawntime X

spawntime is the amount of time for a duck to spawn automatically in chat. This setting can also help fine tune flood controls. If you wish to have multiple ducks spawn automatically, set this value lower than flytime. Time value is in seconds
Recommend 900-1800 seconds (15-30 min)
Pre-config: 1800 seconds

flytime

/msg botname set flytime X

flytime is the amount of time a duck will stay in the area before flying away. If you wish you have multiple ducks spawn automatically, set this value higher than spawntime. The value is in seconds
Recommend 600-1500 seconds (10-25 min)
Pre-config: 1500 seconds

duckexp

/msg botname set duckexp X

duckexp is the amount of xp a player earns for shooting down a normal duck. Golden ducks are 3x this value. Based on game pricing
Recommend 15
Pre-config: 15 xp

duckfear

/msg botname set duckfear X

duckfear is based on points accumulation. Points accumulate every time a player uses !bang. This value can also be used for fine tuning flood controls. The lower the value, the easier it is to scare ducks
Recommend 45-55
Pre-config: 45

duckgold

/msg botname set duckgold X

duckgold is the number that represents what percentage of automatically spawned ducks will turn golden. 1-100
Recommend 30-50
Pre-config: 40

friendrate

/msg botname set friendrate X

friendrate is the number that represents the percentage of luck players will have befriending ducks. 1-100
Recommend 70-75
Pre-config: 71

[Adding & Removing User Access]

User access consists of Botmasters, Admins and Ignored users. It is recommended to only have one or two botmasters, and the rest as admins, but both botmaster and admin can have multiple users.

Only Botmasters may add or remove Admins and other Botmasters. Botmaster and Admin may add or remove ignored users.

Adding or Removing a Botmaster

/msg botname add botmaster username

/msg botname del botmaster username

There must always be at least one username listed as botmaster at all times.

Adding or Removing an Admin

/msg botname add admin username

/msg botname del admin username

Adding or Removing Ignored Users

/msg botname add ignore username

/msg botname del ignore username

Avoid double entries. Do not list the same user in multiple lists. Botmasters have full access, Admins have limited access.

[Configuring Game Rules]

The In-Game Rules and Regulations can be modified to change the game experience for your channel.

Gun Confiscation

/msg botname rules gunconf on

/msg botname rules gunconf off

When turned on, if a player has an accident, or fires their gun without a duck in the area, that player's gun is confiscated until the following duck is shot by someone else. The player's gun will be silently returned upon the following duck being successfully shot down.
Pre-config: ON

Bullet Ricochet

/msg botname rules gunricochet 0
This turns bullet ricochets OFF.

/msg botname rules gunricochet X
This will determine the percentage of a bullet ricocheting when a player misses. 1-100. Recommend 5

Gun ricochet is disabled at 0. If enabled, ricochets will result in a player accident. If gun confiscation is on, the player's gun will also be confiscated.
Pre-config: 5

Searching The Bushes

/msg botname rules thebushes 0
This turns searching the bushes OFF.

/msg botname rules thebushes X
This will determine the percentage of objects found by players when they search the bushes after shooting a duck.

Searching the bushes is disabled at 0. If enabled, 1-100% of players will find objects in the bushes after shooting a duck. Recommend 15
Pre-config: 15

Infinite Ammo

/msg botname rules infammo on

/msg botname rules infammo off

When turned on players will have infinite gun magazines, and infinite bread loafs. Players will still need to reload, but will not run out of ammo.
Pre-config: OFF

No shooting (!bang command set)

/msg botname rules bang on

/msg botname rules bang off

Disabling bang will result in a different game experience with a reduced shop menu and functionality. This setting cannot be disabled unless !bef command set is enabled.
Turning bang off disables the following commands: !bang, !reload, !rearm
Turning bang off disables the following shop items: 1, 2, 3, 4, 5, 6, 7, 8, 9, 15, 17, 18, 23, 24
Pre-config: ON

No befriending (!bef command set)

/msg botname rules bef on

/msg botname rules bef off

Disabling bef will result in a different game experience with a recuded shop menu and functionality. This setting cannot be disabled unless !bang command set is enabled.
Turning bef off disables the following commands: !bef, !bread
Turning bef off disables the following shop items: 19, 20, 21
Pre-config: ON

[Configuring Flood Control]

Flood control settings are currently experimental. The flood control system is designed to reduce virtual load and CPU usage, while also preventing the bot from an excess flood on the IRC network.

The maxducks and duckfear configuration settings can also be used to help fine tune flood control, by setting maxducks and duckfear to their recommended values. In general situations, this should trigger the ducks to flee just before the threshold of flood protection is reached, and puts a limit on how many ducks can exists at one time, thereby reducing demand from users when ducks exist. CTCP events are also monitored under flood control, and have an increased sensativity based on original value. Certain commands like !shop and !duckstats will also trigger flood control quicker, because of their multi-message formats.

/msg botname set flood off
This disables the flood control. Not recommended.

/msg botname set flood X,Y
X = number of commands (recommend 24)
Y = number of seconds (recommend 25)
Pre-config: 24,25

--------------------------------------------------------------
3. Bot Maintenance and Reset Functions
--------------------------------------------------------------

This bot is capable of doing a maintenance procedure on duckhunt.cnf that scans certain sections and key values for old expired time entries and removes them. As time goes on, some values that get set by players will build up in duckhunt.cnf, caused by irregular or infrequent play by players. These functions allow the botmaster to reduce the amount of 'build-up' in duckhunt.cnf. These functions should be used carefully, and are currently experimental.

[Auto Maintenance]

/msg botname maint auto 0
This will turn auto maintenance OFF.

/msg botname maint auto X
This will turn auto maintenance ON to run every X hours. 12-72 only.

Auto maintenance runs every 12-72 hours, per botmaster definition.
Pre-config: 24

[Performing Defined Maintenance]

Defined maintenance functions are tasks that the botmaster can assign at any time, with the following commands.

/msg botname maint do
This performs the regular maintenance procedure (performed by auto maintenance)

/msg botname maint do user xp X
This performs a trimming of the user data. Any player data with xp value lesser or equal to X is permanently deleted. It is not recommended to use this function frequently.

/msg botname maint do user level X
This performs a trimming of the user data. Any player data with a level value lesser or eual to X is permanently deleted. It is not recommended to use this function frequently.

[Bot Reset Functions]

Certain aspects of game data can be reset, or restored with these commands.

/msg botname reset default
This completely resets the bot. It will not change input data (server, port, duckchan, botname, botpass, botmaster). This function WILL delete ALL player data and restore configuration settings to the pre-configured values.

/msg botname reset players
Clear player data only.

/msg botname reset totalshot
Clear total channel shots data only.

/msg botname reset dual
Clear player data and total channel shots data.

--------------------------------------------------------------
4. Botmaster and Admin Commands
--------------------------------------------------------------
This bot contains many commands that can be used by botmasters and admins to not only fine tune the bot for the channel, but also allows easier control of the bot.

[Botmaster and Admin Joint Commands]

These commands are accessible to botmasters and admins.

!duckhunt on/off
Turn DuckHunt ON or OFF

!spawnduck
Spawns a random duck in chat

!spawnduck golden
Spawns a golden duck in chat

!spawnduck normal
Spawns a normal duck in chat

!rearm
Rearm yourself

!rearm username
Rearm specified user

!rearm all
Return all confiscated guns

!disarm username
Confiscate username's gun (v1.1.4 only)

!flood
Flood control override

/msg botname duckstats
View your stats

/msg botname duckstats username
View another player's stats

/msg botname spawnduck
Spawns a random duck in chat

/msg botname spawnduck normal
Spawns a normal duck in chat

/msg botname spawnduck golden
Spawns a golden duck in chat

/msg botname add ignore username
Adds username to the ignore list

/msg botname del ignore username
Remove username from the ignore list

[Botmaster Commands]

configuration commands

maintenance and reset functions

!exit
Shut down the bot

/msg botname duckhunt on/off
Turn DuckHunt ON or OFF

/msg botname do
This command sends raw IRC commands thru the bot.
Example: /msg botname PRIVMSG #duckhunt :Hello everyone!

/msg botname add
/msg botname del

/msg botname add admin username
Add username to admin list. Remove the user from other lists first.

/msg botname del admin username
Remove username from admin list.

/msg botname add botmaster username
Add username to botmaster list. Remove the user from other lists first.

/msg botname del botmaster username
Remove username from botmaster list. Cannot remove yourself, and there must always be 1 botmaster listed at all times.

/msg botname rules - See Configuration for more info on these commands.

/msg botname rules infammo on/off
Turn infinite ammo ON or OFF. Users will have infinite bread loafs and/or ammo magazines.

/msg botname rules gunconf on/off
Turn gun confiscation ON or OFF.

/msg botname rules bang on/off
Turns !bang, !reload and other related functions ON or OFF.

/msg botname rules bef on/off
Turns !bef, !bread and other related functions ON or OFF.

/msg botname rules gunricochet 0-100
Setting to 0 disables bullet ricochets. 1-100 for the percentage of misses that will ricochet. (Recommend 5)

/msg botname rules thebushes 0-100
Setting to 0 disables searching in the bushes. 1-100 for the percentage of items found while searching the bushes after shooting a duck. (Recommend 15)

/msg botname set - See Configuration for more info on these commands.

/msg botname set maxducks X
X = total number of ducks that can exist at one time. Recommend 3-6.

/msg botname set spawntime X
X = time in seconds between duck spawns. Recommend 900-1800 seconds (15-30 min)

/msg botname set flytime X
X = time in seconds until the spawned duck flies away. Recommend 600-1500 seconds (10-25 min)

/msg botname set duckexp X
X = amount of xp earned for shooting/befriending a duck. Golden ducks are 3x this value. Recommend 15

/msg botname set duckfear X
X = 1-100, sets number of fear points to scare away ducks. Recommend 45-55

/msg botname set duckgold X
X = 1-100, percentage of randomly spawned ducks that will turn golden. Recommend 40-50

/msg botname set friendrate X
X = 1-100, percentage of luck/success when befriending ducks. Recommend 73

/msg botname maint - See: Bot Maintenance and Reset Functions for more information on this command

/msg botname maint auto 0
This turns auto maintenance OFF

/msg botname maint auto 12-72
Turns auto maintenance ON to run every 12-72 hours

/msg botname maint do
Performs the regular maintenance procedure.

/msg botname maint do user xp/level X
Deletes all player entries with xp or level less than or equal to X

/msg botname reset - See: Bot Maintenance and Reset Functions for more information on this command

/msg botname reset default
Restore bot settings to default, deletes all player data. Does not delete username, password, server, channel.

/msg botname reset players
Clears all player data

/msg botname reset totalshot
Clears the total shot data

/msg botname reset dual
Clears all player data and total shot data

/msg botname set flood

/msg botname set flood
Displays current flood settings

/msg botname set flood off
Turn off flood protection

/msg botname set flood on X,Y
Turn on flood prection to X commands in Y seconds. Recommend 24,25