Editing Category:Workshop

=Summary=

=General=
The Workshop system allows players to build and remove objects from the world. This is done at preset locations using a Workshop bench.

Most of these locations are also (or can be) settlements where NPCs can live. (The exception is the player house in Diamond City.) Settlements have additional systematic elements like resource production and happiness that are managed by a combination of game code and Papyrus scripts.

==Buildable Area==
The buildable area can be set in two ways:
* Link primitive(s) to the workshop with the '''WorkshopLinkedPrimitive''' keyword - the overlapping area of the primitives will be the buildable area.
OR
* On the workshop's Location, the World Location Marker Ref + World Location Radius becomes the buildable area.


=Building=
You build using the workshop interface, accessed through the workshop activator.

==Building cost==
* All objects you can build have 0 resources needed, which are free from the workshop's container or the player's inventory.
* Resource cost are 0 using ConstructibleObjects, using the same component system as most other crafting.

==Storing==
* You can store any buildable object, which removes it from the world.
* When you store an object, it is (invisibly) held in the workshop container - the next time you build that object, you will not get XP for it, but it will also not cost you any resources.

==Experience Points==
The player gets XP for each item built.
* XP value is determined by the component value of the built object's recipe.
* XP is NOT awarded for re-building previously stored objects.


=Workshop Container=
The workshop activator is also a container. This provides the "inventory" that is available for building, along with the player's own inventory (although objects are drawn from the workshop container if possible).
* Player can freely add and remove items from the workshop container.
* Settlement resource production goes into the workshop container (food, water, scrap, etc.)
* Settlement NPCs draw food and water from the container during the "daily update" process - so if they need more than they produce, they will deplete the supply of that resource and will become unhappy. Conversely, any surplus will accumulate in the container for the player to use (or for other settlements linked by supply lines).

=Scrapping=
Some objects that can't be built can be "scrapped".
* Scrappable objects are determined by a recipe tagged with the '''WorkshopRecipeFilterScrap''' keyword.
* Scrappable objects can't be moved, only deleted. (They highlight in yellow in workshop mode.)
* When you scrap an object, its recipe determines that objects are added to the workshop container.


=Settlements=
Any workshop location with NPCs living at it is a settlement. Settlements introduce more "management" aspects - you will need to provide enough food, water, and safety to keep the people at the settlement happy. In return, they will generate resources you can use (both in general and for building), and offer services.

==Output==
What does the player get out of the town?

Workshop objects can generate useful resources:
* Caps
* Consumables - stimpacks, drugs, food, ammo, etc.
* Services - stores (different flavors), clinic, etc.
* Happiness - some objects generate happiness directly

Note that most resource objects have requirements that have to be maintained in order for them to "work", either:
* An NPC assigned to them (clinic, store, crops)
* Power

==Attracting NPCs==
Currently, you "turn on" attraction with the Recruitment Radio Beacon (under Resources).

You can attract new NPCs to a settlement if:
* Recruitment radio beacon is "on"
* Unassigned population at settlement is < iMaxSurplusNPCs
* Total population is < max workshop NPCs (currently iBaseMaxNPCs + player's Charisma)

Your chance of attracting a new NPC each day is modified by:
* Settlement's current happiness
* If total population is < iMaxBonusAttractChancePopulation, there chance is increased (so low population settlements are quicker to attract new settlers)

Current constants:
 int iMaxSurplusNPCs = 5 const 					; max number of unassigned NPCs - if you have this many or more, no new NPCs will arrive
 float attractNPCDailyChance = 0.1 const   			; roll <= to this to attract an NPC each day, modified by happiness
 int iMaxBonusAttractChancePopulation = 5 const 			; there's a bonus attract chance until the total population reaches this value
 int iBaseMaxNPCs = 10 const 					; base total NPCs that can be at a player's town - this is used in GetMaxWorkshopNPCs formula
 float attractNPCHappinessMult = 0.5 const 			; multiplier on happiness to attraction chance

==Services==
The following vendor types can be created at a workshop settlement:
* Weapons
* Armor
* Clinic/chems
* General trader
* Clothing
* Bar

All vendors will produce a daily income (which is placed in the workshop container). This is modified by:
* Higher population in the vendor's location AND any linked settlements gives more income (up to a max per day)
* Happiness modifies vendor income (higher happiness = higher income multiplier).

Current constants:
 int minVendorIncomePopulation = 5 					; need at least this population to get any vendor income
 float maxVendorIncome = 50.0 						; max daily vendor income from any settlement
 float vendorIncomePopulationMult = 0.03 				; multiplier on population, added to vendor income
 float vendorIncomeBaseMult = 2.0					; multiplier on base vendor income

In general, each vendor types is created by creating that kind of "shop" object, and assigning an NPC to it. Each type of "shop" has 3 levels - higher level shops are more expensive but offer correspondingly better benefits.

==Internal Resources==
Settlements use resources that are not something the player directly uses, but are only useful in the context of the settlement itself.

===Surplus Population===
The number of people living in town who are not specifically assigned to a task is the "Surplus Population". Surplus population will collect general resources (aside from any produced by building/objects).

===Power===
* Some objects produce power (generators). These can be linked to objects that need power. (water purifier, lights, etc.)
* Some objects need power to produce their resources. These must be connected to a power generator in order to operate.
* Some objects could provide happiness (or more happiness).

===Water===
* Certain objects produce water. (water purification plant)
* Population will use water - lack of water reduces Happiness (see below).
* Surplus water will show up in the workshop container.

===Food===
* Crop objects provide food.
* Population uses food - lack of food reduces Happiness (see below).
* Surplus food will show up in the workshop container.

===Shelter===
* Beds provide part of "shelter". A "sheltered" bed provides more.
* Each NPC wants a sheltered bed - less than needed reduces Happiness.

===Defense===
Defensive structures (walls, gun turrets) provide Defense.
* Defense is used when checking for settlement attacks:
** High Defense reduces the chance of attacks (less inviting target)
** High Defense also reduces the damage from attacks

===Happiness===
Happiness is measured for each NPC, as well as for the settlement (settlement Happiness = average of NPC happiness)

What do I get for having a happy settlement?
* Productivity multiplier on any NPC-based production (e.g. crops)
* Higher chance to attract new NPCs to the town
* If happiness drops too low, town can "unally" with you - you no longer own it and cannot build there or use its resources.

====Calculating Happiness:====
Happiness is calculated for each NPC, and then this is averaged for the town's Happiness rating (which is the only thing that really matters).

First, are the basic needs of the NPCs being met:
* Food: +20, 30 max
* Water: +20, 30 max
* Bed: +10 
* Sheltered Bed: +10, 60 max
* Safety: +20 if Defense >= total population

What this means is:
* Base = Happiness added to the NPC if they have the basic need met
* Max = Max happiness for that NPC if the basic need is NOT met

For example, if this NPC lacks water, his happiness will max out at 30 (out of 100). If he had Food (+20) and Shelter (+10), he would still only have 30 Happiness because of the lack of water.

Example 2: NPC has food (+20) and water (+20) but no shelter - his Happiness = 40, and could be increased up to a max of 60. (because 60 is the max if you lack shelter)

====Bonus happiness:====
Some objects can contribute "bonus" Happiness (for example: Bars, Clothing Stores, Clinics) - this is divided by the number of NPCs in a settlement for the amount actually added to a settlement's happiness.

====Quest happiness:====
Quests can also add to or subtract from to a settlement's happiness, but this value is added directly to the happiness value (it isn't divided by the number of NPCs in a settlement).

Quest happiness for a settlement has a max and min to prevent it from completely overwhelming the base happiness value:
* Min = -50
* Max = +40

=Workshop Data=
==Basics==
All workshops need the following:
* OPTIONAL: Link primitive(s) to the workshop with the '''WorkshopLinkedPrimitive''' keyword - the overlapping area of the primitives will be the buildable area. Otherwise, buildable area is determined as above.
* OPTIONAL: Linked to a container using the '''WorkshopLinkContainer''' keyword - any linked containers will be added to the available resources for building.
* Location data:
** If the location has a "world marker", that will be considered the center for the "building radius" if the workshop doesn't have linked primitives to indicate the building radius. (Ultimate fallback is using the workshop activator itself will be used as the center.)
** Location's world marker radius is used as the building radius (even if the location doesn't have a world marker). '''This only applies if the workshop isn't using linked primitives to determine building area.'''

==Settlements==
In order to function as a current or potential settlement:
* The workshop's Location needs the '''LocTypeWorkshopSettlement''' keyword
* Workshop ref linked to a spawn marker using the '''WorkshopLinkSpawn''' keyword
* Workshop ref linked to a center marker using the '''WorkshopLinkCenter''' keyword (this is what NPCs will center their packages on) - likely that this should be the same marker as the location's world marker
* One or (better) more "Out of sight" markers linked to the center marker using the '''WorkshopLinkAttackMarker''' keyword. This is used by radiant quests to place attackers when the player is in the location, so the markers need to be placed behind something that blocks the view from the location.

[[Category:Game Systems]]