Mod Config

Mod Config

This page explains the configuration files that control Flan's Mod Ultimate 2.0. It is written for players, server owners, and modpack makers who want to tune the mod without editing Java code.

For content-pack .txt parameters such as gun, bullet, armor, and grenade fields, see Config Reference. For bulk edits applied through JSON groups, see Category System.

Where the Files Are

After the mod starts once, these files are created in the Minecraft config folder:

File	Purpose
config/flansmodultimate-common.toml	Gameplay and server-side rules. On multiplayer, the server's common config is authoritative.
config/flansmodultimate-client.toml	Client-only input, HUD, model loading, and rendering defaults. Each player can keep their own values.
config/flansmodultimate-content-loading.properties	Content pack path, content loading regeneration, and default category loading.
config/flansmodultimate/*.json	User category files. These let you apply content-pack parameters to groups of items.
config/flansmodultimate/default/*.json	Built-in default categories copied by the mod. Use these as examples; put your own changes in the files one folder above.

On a dedicated server, the same paths are inside the server folder. For multiplayer, keep content packs and category files matched between server and clients unless the change is purely visual.

Editing Rules

• Stop the game or server before changing content loading settings or category files.
• Common and client TOML settings may be picked up by Forge while running, but a restart is the safest way to test changes.
• Content loading settings and category JSON files are loaded during startup. Restart after editing them.
• In TOML files, booleans are true or false, numbers are not quoted, and strings/enums are quoted when the generated file uses quotes.
• In .properties files, use key=value.
• In JSON category files, use valid JSON. Comments are not allowed.

Common Config

File: config/flansmodultimate-common.toml

These settings affect gameplay. In multiplayer, clients receive the server's common config while connected, so changing a client's local common file will not override a server.

General Settings

Setting	Expected value	Default	Purpose
addAllPaintjobsToCreative	true or false	true	Shows every paintjob variant in creative mode.
disableCrosshairForGuns	true or false	true	Hides the normal crosshair while holding guns, except melee weapons.
explosionBreakBlocks	true or false	true	Allows Flan's Mod explosions to break blocks.
flanExplosionsDropBlocks	true or false	true	Makes blocks broken by Flan's Mod explosions drop items. This only matters if explosions can break blocks.
bonusRegenAmount	Integer, 0 to 1000	0	Adds extra player health regeneration. Use with increased max health setups.
bonusRegenTickDelay	Integer ticks, 0 to 1000	80	Delay between bonus regeneration heals. Minecraft runs 20 ticks per second; vanilla natural regen uses 80.
bonusRegenFoodLimit	Integer, 0 to 20	18	Food level required before bonus regeneration can happen.

Entity Tracking Settings

Setting	Expected value	Default	Purpose
deployedGunTrackingRange	Integer blocks, 1 to 4096	64	Server-side tracking range for deployed guns.
aaGunTrackingRange	Integer blocks, 1 to 4096	128	Server-side tracking range for AA guns.

These values control when the server sends the entity to clients. They are read while entity types are registered, so restart the game or server after changing them.

Damage Settings

Setting	Expected value	Default	Purpose
headshotDamageModifier	Decimal number	2.0	Multiplies damage for head hits.
chestshotDamageModifier	Decimal number	1.0	Multiplies damage for chest/body hits.
armshotDamageModifier	Decimal number	0.7	Multiplies damage for arm hits.
legshotModifier	Decimal number	0.8	Multiplies damage for leg hits.
vehicleWheelSeatExplosionModifier	Decimal number, 0.0 to 1.0	1.0	Reduces explosion damage when the explosion hits a vehicle wheel or seat.

Values above 1.0 increase damage. Values below 1.0 reduce damage.

Armor Settings

Setting	Expected value	Default	Purpose
breakableArmor	0, 1, or 2	2	Controls armor durability behavior. 0 means armor does not break, 1 makes all armor breakable, 2 uses each armor's own config.
defaultArmorDurability	Integer	500	Durability used when breakableArmor = 1.
defaultArmorEnchantability	Integer	0	Default enchantability for armor. 0 means not enchantable. Higher values give better enchantment rolls.
forceDefenseAsModernArmor	true or false	false	Makes Defence / Defense in armor content files behave like modern Minecraft armor points instead of the legacy ratio-based armor system.

DamageReduction and OtherDefence / OtherDefense keep their legacy behavior even when forceDefenseAsModernArmor is enabled.

Gun Settings

Setting	Expected value	Default	Purpose
gunsAlwaysUsableByPlayersInCreativeMode	true or false	true	Allows creative-mode players to use guns even if the gun content file says UsableByPlayers false.
gunDamageModifier	Decimal number, 0.0 to 100.0	1.0	Global multiplier for gun damage.
gunRecoilModifier	Decimal number, 0.0 to 100.0	1.0	Global multiplier for gun recoil.
gunDispersionModifier	Decimal number, 0.0 to 100.0	1.0	Global multiplier for gun Dispersion values.
gunAccuracySpreadModifier	Decimal number, 0.0 to 100.0	1.0	Global multiplier for gun Accuracy and Spread values.
defaultADSSpreadMultiplier	Decimal number, 0.0 to 10.0	0.2	Default spread multiplier while aiming down sights. Lower values make aimed shots tighter.
defaultADSSpreadMultiplierShotgun	Decimal number, 0.0 to 10.0	0.8	Default aimed spread multiplier for multishot guns such as shotguns.
cancelReloadOnWeaponSwitch	true or false	true	Cancels reloads when the player switches to a different item.
combineAmmoOnReload	true or false	true	Combines unloaded ammo with damaged or partially used ammo in the inventory.
ammoToUpperInventoryOnReload	true or false	false	Tries to place unloaded ammo in the upper inventory first.
realisticRecoil	true or false	false	Enables the alternate recoil behavior.
enableSightDownwardMovement	true or false	true	Allows the sight to move downward after shooting.

For broad balancing, start with global multipliers. For per-weapon tuning, use the Category System or edit the weapon's content-pack file.

Shootable Settings

These settings affect bullets, grenades, shells, rockets, and other shootable items.

Setting	Expected value	Default	Purpose
shootablesCanBreakGlass	true or false	true	Allows guns and grenades to break glass.
newDamageSystemDamageReference	Decimal number	5.0	Baseline used by the kinetic-energy damage system when a shootable has Mass.
newDamageSystemExplosiveDamageReference	Decimal number	80.0	Baseline damage for explosive-mass calculations when a shootable has ExplosiveMass.
newDamageSystemExplosivePowerReference	Decimal number	4.0	Baseline explosion power for explosive-mass calculations.
newDamageSystemExplosiveRadiusReference	Decimal number	10.0	Baseline explosion radius for explosive-mass calculations.
newDamageSystemBlastToExplosionRadiusRatio	Decimal number, 0.0 to 10.0	2.5	Ratio between blast damage radius and the visual/block-breaking explosion radius.
shootableProximityTriggerFriendlyFire	true or false	false	Allows proximity-triggered shootables to trigger from allies and cause friendly fire.
shootableDefaultRespawnTime	Integer ticks, 0 or higher	0	Default maximum despawn time for shootables. 0 means no default despawn time.
lockOnRange	Decimal number, blocks	128.0	Range used by lock-on missiles when searching for targets.
flakParticlesRange	Integer blocks	256	Range for sending flak particle packets to clients.
entityHitParticleRange	Decimal number, blocks	64.0	Range for sending entity-hit particle packets to clients.
blockHitParticleRange	Decimal number, blocks	64.0	Range for sending block-hit particle packets to clients.
smokeParticlesCount	Integer, 0 or higher	50	Number of smoke particles spawned per smoke particle packet.
smokeParticlesRange	Decimal number, blocks	32.0	Range for sending smoke particle packets to clients.

The new damage-system reference settings are advanced balance controls. Change them when you want to rebalance a whole pack around Mass or ExplosiveMass, not when you only want to adjust one bullet or grenade.

Particle range settings affect how far the server sends visual-effect packets. Larger values can increase network and client particle load on busy servers.

Sound Settings

Setting	Expected value	Default	Purpose
soundRange	Decimal number, blocks	48.0	Range for general sound packets. Also affects volume handling.
gunFireSoundRange	Decimal number, blocks	128.0	Range for gunfire sounds.
explosionSoundRange	Decimal number, blocks	256.0	Range for explosion sounds.

Larger values make sounds carry farther and may increase how much sound traffic is sent on busy servers.

Penetration System Settings

Setting	Expected value	Default	Purpose
useNewPenetrationSystem	true or false	false	Enables the newer penetration behavior.
enableBlockPenetration	true or false	false	Allows block penetration when the penetration system and projectile settings permit it.
blockPenetrationModifier	Decimal number, 0.0 to 100.0	0.0	Default block penetration power. Individual bullets can override this.
blocks	TOML string list	[]	Per-block penetration data.

Each blocks entry uses this format:

blocks = [
    "minecraft:stone; 3.0; false",
    "minecraft:glass; 0.3; true"
]

The format is:

namespace:block; hardness; breaksOnPenetration

hardness is a decimal number. breaksOnPenetration is true if the block should break when penetrated, or false if it should remain.

Digital Ammo System Settings

Setting	Expected value	Default	Purpose
enableDigitalAmmoSystem	true or false	false	Enables a virtual per-player ammo pool instead of relying only on physical ammo items.
digitalAmmoDefaultAmount	Integer	100	Starting amount for each digital ammo type when a player first joins.
digitalAmmoMaxAmount	Integer	1000	Maximum stored amount per ammo type.
digitalAmmoNumTypes	Integer, 1 to 20	7	Number of different digital ammo types.
digitalAmmoSupplyBlocks	TOML string list	[]	Blocks that refill digital ammo when used.
digitalAmmoSupplyAmount	Integer	100	Amount restored for each ammo type when using a supply block.

Example supply block setup:

digitalAmmoSupplyBlocks = [
    "minecraft:iron_block",
    "minecraft:barrel"
]
digitalAmmoSupplyAmount = 250

Use namespaced block IDs such as minecraft:barrel or yourmod:ammo_crate.

Enchantment Module

Setting	Expected value	Default	Purpose
enchantmentModuleEnabled	true or false	true	Enables the Flan's Mod enchantment module, including Steady, Nimble, Lumberjack, Duelist, Sharpshooter, and Juggernaut.

Client Config

File: config/flansmodultimate-client.toml

These settings only affect the local client. They do not change server rules.

General Settings

Setting	Expected value	Default	Purpose
showPackNameInItemDescriptions	true or false	true	Shows the content pack name in item tooltips.
loadAllModelsInCache	true or false	false	Loads and caches all models during resource reload. Leave this off unless you specifically need it.
showShootableDurabilityBars	true or false	true	Shows a durability-style bar for shootable items when their current round item is not full.
showArmorDamageAbsorptionBar	true or false	true	Shows the HUD bar for legacy armor damage absorption.

loadAllModelsInCache can use a lot of RAM and make resource reloads much slower when many content packs are installed.

Entity Rendering Settings

Setting	Expected value	Default	Purpose
deployedGunRenderDistance	Integer blocks, 1 to 4096	64	Client-side visual render distance for deployed guns.
aaGunRenderDistance	Integer blocks, 1 to 4096	128	Client-side visual render distance for AA guns.

These settings only affect client-side rendering. On multiplayer, the server still controls whether the entity is tracked and synced through the common tracking range.

Input Settings

Setting	Expected value	Default	Purpose
shootButton	Mouse button enum	"MOUSE_LEFT"	Main-hand gun shooting or primary function.
shootButtonOffhand	Mouse button enum	"MOUSE_RIGHT"	Offhand gun shooting or primary function.
aimButton	Mouse button enum	"MOUSE_RIGHT"	Aiming or secondary function.
aimType	"HOLD" or "TOGGLE"	"TOGGLE"	Whether aiming is held while pressing the button or toggled on/off.

Allowed mouse button values:

MOUSE_LEFT
MOUSE_RIGHT
MOUSE_MIDDLE
MOUSE_4
MOUSE_5

Gun Rendering Settings

Setting	Expected value	Default	Purpose
enableArms	true or false	true	Renders player arms with guns.
enableGunAnimationsInThirdPerson	true or false	true	Shows reload, melee, and other gun animations in third person, including on other players.
enableWeaponSprintStance	true or false	true	Lowers weapons while sprinting.
enableRandomSprintStance	true or false	false	Generates a unique sprint stance per weapon using the weapon name as a seed.

Translucent Rendering Defaults

These options choose whether certain item types use translucent rendering by default. If a content file explicitly has TranslucentRendering true, it remains translucent regardless of these defaults.

Setting	Expected value	Default	Purpose
alwaysEnableArmorsTranslucentRenderingByDefault	true or false	false	Uses translucent rendering by default for armors.
alwaysEnableGunsTranslucentRenderingByDefault	true or false	true	Uses translucent rendering by default for guns.
alwaysEnableGrenadesTranslucentRenderingByDefault	true or false	true	Uses translucent rendering by default for grenades.
alwaysEnableBulletsTranslucentRenderingByDefault	true or false	true	Uses translucent rendering by default for bullets.
alwaysEnableAttachmentsTranslucentRenderingByDefault	true or false	true	Uses translucent rendering by default for attachments.
alwaysEnableAAGunsTranslucentRenderingByDefault	true or false	false	Uses translucent rendering by default for AA guns.

Disable a translucent default if a large pack has rendering issues or if you want a more opaque-looking item type by default.

Content Loading Config

File: config/flansmodultimate-content-loading.properties

This file controls where the mod looks for content packs and how it prepares generated content assets.

Setting	Expected value	Default	Purpose
contentPacksRelativePath	Folder path relative to .minecraft	flan	Folder where external content packs are loaded from. The default means .minecraft/flan.
forceRegenContentPacksAssetsAndIds	true or false	false	Forces content-pack asset and ID regeneration on startup. This can significantly increase startup time.
contentLoadingSystemVersion	Integer	3	Internal content-loading version. Normally do not edit this.
useDefaultCategories	true or false	true	Loads the mod's built-in default categories from config/flansmodultimate/default.

Use forceRegenContentPacksAssetsAndIds=true when you have changed content packs in a way that adds or changes generated assets or IDs. After one successful startup, set it back to false so every launch does not repeat the expensive regeneration.

Example:

contentPacksRelativePath=flan
useDefaultCategories=true
forceRegenContentPacksAssetsAndIds=false
contentLoadingSystemVersion=3

Common Setups

Disable Explosion Block Damage

explosionBreakBlocks = false
flanExplosionsDropBlocks = false

Make Headshots More Lethal

headshotDamageModifier = 3.0

Reduce Global Gun Recoil

gunRecoilModifier = 0.75

Enable Digital Ammo With Supply Blocks

enableDigitalAmmoSystem = true
digitalAmmoDefaultAmount = 100
digitalAmmoMaxAmount = 1000
digitalAmmoSupplyBlocks = [
    "minecraft:barrel"
]
digitalAmmoSupplyAmount = 250

Disable Built-In Default Categories

In flansmodultimate-content-loading.properties:

useDefaultCategories=false

This gives you full control over category-based edits, but also removes all built-in category tuning supplied by the mod.

Troubleshooting

Problem	What to check
Changes do not affect a multiplayer server	Edit the server's config. The server common config overrides client common settings while connected.
Category changes do not apply	Restart the game or server, verify the item short name, and check the correct category file for that item type.
Game fails to load after editing TOML	Check quotes, commas, brackets, and boolean values. Compare against the generated default file.
Startup becomes much slower	Check loadAllModelsInCache and forceRegenContentPacksAssetsAndIds.
Content pack changes do not show	Try forceRegenContentPacksAssetsAndIds=true for one launch, then set it back to false.
Default categories are still affecting items	Set useDefaultCategories=false, or override the same properties in your user category files.