Section One: Preparing Your Server
Before you begin installing the addon you will need to prepare your server. There are some addons you won't need and some that you will. Make sure to do the following:
- Get the Advanced Lightsaber Content Package by clicking here.
- Get all required content included in that addon (Except for gExplo, this is a client file)
Section Two: Preparing Your Clients
Your clients will just need the content package and all required items in the content package. If they are seeing T-Pose, make sure they restart their game and check for conflicting animation addons.
If your clients encounter any issues, have them navigate here to submit a support request or to read the Knowledgebase to see if it has been already answered.
Section Three: Installing the Addon and Configuring the Essentials
There are a couple of configuration options you need to configure before usage, otherwise the experience may not be optimal for your server. Although the addon will work right out of the box, it may not work the best or to your liking without configuring. Do the following in this exact order:
- Download the DLL off of the package's page
- Drag and drop the DLL according to your server's OS into your server's root directory lua/bin folder
- Download your package and extract it
- Drop the folder you get from the ZIP into your addons folder.
- Go to the lua/wos/advswl/config folder in the addon.
- Configure all files in the character, crafting, general, lightsaber, and skills directories
Forms are in the: lua/wos/advswl/forms files.
Section Four: Creating Custom Lightsabers (Part A)
This addon allows you to create your own lightsabers with different stats, allowing you to have unique gameplay choices (such as high force, low damage, no burn damage, customize abilties, etc.) The steps are very easy and require little lua knowledge.
- Copy any weapon_lightsaber_*** lua file from the weapons folder
- Paste it in the same folder and rename it to something unique (EX: weapon_lightsaber_vanguard)
- Open up the file and edit the items BELOW the dotted line that says "Things you will edit"
- Save the file, and spawn it in game through the Lightsaber Category under the weapons tab.
The list of options, descriptions, and example of each entry are listed below. Please pay attention to the type of value expected after the entry as well as the presence of any commas, and quotations. The description will explain a little of what it does and the example shows an entry IF you decide to use it.
Entry: SWEP.PrintName = "STRING"
Description: The name of the weapon in the weapons category/selection
Example: SWEP.PrintName = "The King's Saber"
Entry: SWEP.Class = "STRING"
Description: The file name of this weapon.
Example: If your swep file name is weapon_lightsaber_vanguard.lua then SWEP.Class = "weapon_lightsaber_vanguard"
Entry: SWEP.DualWielded = BOOLEAN
Description: Should this lightsaber be a dual wielded lightsaber?
Example: To make this lightsaber be dual wielded ( one in each hand ), we set SWEP.DualWielded = true
Entry: SWEP.CanMoveWhileAttacking = BOOLEAN
Description: Can you move around while you swing? This is off by default due to the sliding animations while moving. The attacks automatically lunge you to the direction of the attack with this off as well.
Example: To activate this, we set SWEP.CanMoveWhileAttacking = true
Entry: SWEP.SaberDamage = NUMBER
Description: The amount of damage a lightsaber does when a swing hits somebody. Heavy attacks do 1.5x the amount of damage set here.
Example: To do 30 damage, we set SWEP.SaberDamage = 30
Entry: SWEP.SaberBurnDamage = NUMBER
Description: The amount of damage a lightsaber does when it comes in contact with a player when not swinging. This is the damage it does when you run into somebody's blade while they are idle or running.
Example: To do 0 damage and effectively disable it, we set SWEP.SaberBurnDamage = 0
Entry: SWEP.MaxForce = NUMBER
Description: The maximum force energy a user has ( this is that blue bar at the bottom ) Be aware that the percent on the force meter will not change as it is automatically calculated.
Example: To set the Max Force to 200, we set SWEP.MaxForce = 200
Entry: SWEP.RegenSpeed = NUMBER
Description: The regeneration rate of the force energy per tick. This is a multiplier value, so 0.5 would mean half speed, and 2 means double speed.
Example: To regenerate our force at 3 times the speed, we set SWEP.RegenSpeed = 3
Entry: SWEP.CanKnockback = BOOLEAN
Description: If we hit somebody with a lightsaber, should they get knocked back?
Example: To disable knockback, we set SWEP.CanKnockback = false
Entry: SWEP.ShouldStun = BOOLEAN
Description: When we hit somebody with a lightsaber, should they momentarily be stunned ( triggers an invincibility window while they are stunned as well )
Example: To disable stun-on-hit, we set SWEP.ShouldStun = false
Entry: SWEP.BlockDrainRate = NUMBER
Description: How much force energy do we lose per tick when we are holding down the block button ( THIS NUMBER SHOULD ALWAYS BE A SMALL DECIMAL IN RANGE 0.01 - 0.5 ). The formula for calculating ( loss per second ) = NUMBER/TICKRATE
Example: If we want to lose one force per second on a 64 tick server, we set SWEP.BlockDrainRate = 1/64
Entry: SWEP.FirstPerson = BOOLEAN
Description: Should this lightsaber start off as a First Person lightsaber? ( The view may be toggled with the wos_togglefirstperson console command )
Example: If we want the user to be in first person when they first equip the weapon, we set SWEP.FIrstPerson = true
Entry: SWEP.ForcePowerList = { "STRING1", "STRING2", ... }
Description: What force powers should this lightsaber have? For the exact STRING values, see the KEYS in the "lua/wos/advswl/forcepowers/wos_forcematerialbuilding.lua" file. As you keep adding force powers, add a comma at the end!
Example 1: To give this lightsaber Leap, Heal, and lightsaber throwing, we set SWEP.ForcePowerList = { "Force Leap", "Force Heal", "Saber Throw" }
Example 2: To give this lightsaber no force powers, we set SWEP.ForcePowerList = {}
Entry: SWEP.DevestatorList = { "STRING1", "STRING2", ... }
Description: What devestators should this lightsaber have? For the exact STRING values, see the KEYS in the "lua/wos/advswl/devestators/wos_devmaterialbuilding.lua" file. As you keep adding devestators, add a comma at the end! You MUST give them Meditation/Channel Hatred force powers if you want them to be able to use Devestators!
Example 1: To give this lightsaber Kyber Slam, we set SWEP.DevestatorList = { "Kyber Slam" }
Example 2: To give this lightsaber no devestators, we set SWEP.DevestatorList = {}
Entry: SWEP.UseSkills = BOOLEAN
Description: Should this lightsaber inherit properties from the user's Skill Trees?
Example: If we want the user's skills to be applied onto the lightsaber, we set SWEP.UseSkills = true
Entry: SWEP.PersonalLightsaber = BOOLEAN
Description: Should this lightsaber be considered a personal lightsaber and inherit properties from the user's crafting bench? ( NOT RECOMMENDED! STICK TO USING THE PERSONAL LIGHTSABER WEAPON )
Example: If we want this weapon to be considered the personal lightsaber of a user, we set SWEP.PersonalLightsaber = true
Section Five: Creating Custom Lightsabers (Part B)
When you are creating lightsabers you may also choose to overwrite the settings that the user has chosen with the tool gun. This allows you to force a player to use a specific model, color, sound, and etc.
Like in ( Part A ), the entry, description, and examples of the overwriting settings are below. Pay attention to the formatting, the use of any brackets, commas, and etc. Entries with || indicate it will accept either entry.
Entry: SWEP.UseModel = "STRING" || false
Description: Do we overwrite the player's hilt option from the toolgun and use this model instead? Enter the model path to overwrite with, or set to false to use the tool gun option.
Example 1: To force this lightsaber to use Darth Vader's hilt, we set SWEP.UseHilt = "models/sgg/starwars/weapons/w_vader_saber_hilt.mdl"
Example 2: To use the tool gun option, we set SWEP.UseHilt = false
Entry: SWEP.UseLength = NUMBER || false
Description: Do we overwrite the player's length option from the toolgun and use this size instead? Enter the number to overwrite with, or set to false to use the tool gun option.
Example 1: To force this lightsaber to use a length of 42, we set SWEP.UseLength = 42
Example 2: To use the tool gun option, we set SWEP.UseLength = false
Entry: SWEP.UseWidth = NUMBER || false
Description: Do we overwrite the player's width option from the toolgun and use this size instead? Enter the number to overwrite with, or set to false to use the tool gun option.
Example 1: To force this lightsaber to use a width of 6, we set SWEP.UseWidth = 6
Example 2: To use the tool gun option, we set SWEP.UseWidth = false
Entry: SWEP.UseColor = Color( NUMBER_RED, NUMBER_GREEN, NUMBER_BLUE ) || false
Description: Do we overwrite the player's blade color option from the toolgun and use this color instead? Enter the RGB Color values to overwrite with, or set to false to use the tool gun option.
Example 1: To force this lightsaber to use a RED color, we set SWEP.UseColor = Color( 255, 0, 0 )
Example 2: To use the tool gun option, we set SWEP.UseColor = false
Entry: SWEP.UseDarkInner = NUMBER || false
Description: Do we overwrite the player's inner blade option from the toolgun and use this core instead? Enter the number to overwrite with, or set to false to use the tool gun option.
Example 1: To force this lightsaber to use a dark inner blade, we set SWEP.UseDarkInner = 1
Example 2: To force this lightsaber to use a white inner blade, we set SWEP.UseDarkInner = 0
Example 3: To use the tool gun option, we set SWEP.UseDarkInner = false
Entry: SWEP.UseLoopSound = "STRING" || false
Description: Do we overwrite the player's humming sound option from the toolgun and this sound instead? Enter the sound path to overwrite with, or set to false to use the tool gun option.
Example 1: To force it to play kylo ren's humming sound, we set SWEP.UseLoopSound = "lightsaber/kylo_hum.wav"
Example 2: To use the tool gun option, we set SWEP.UseLoopSound = false
Entry: SWEP.UseSwingSound = "STRING" || false
Description: Do we overwrite the player's swinging sound option from the toolgun and this sound instead? Enter the sound path to overwrite with, or set to false to use the tool gun option.
Example 1: To force it to play kylo ren's swinging sound, we set SWEP.UseSwingSound = "lightsaber/kylo_swing.wav"
Example 2: To use the tool gun option, we set SWEP.UseSwingSound = false
Entry: SWEP.UseOnSound = "STRING" || false
Description: Do we overwrite the player's ignition sound option from the toolgun and this sound instead? Enter the sound path to overwrite with, or set to false to use the tool gun option.
Example 1: To force it to play kylo ren's ignition sound, we set SWEP.UseOnSound = "lightsaber/kylo_on.wav"
Example 2: To use the tool gun option, we set SWEP.UseOnSound = false
Entry: SWEP.UseOffSound = "STRING" || false
Description: Do we overwrite the player's extinguish sound option from the toolgun and this sound instead? Enter the sound path to overwrite with, or set to false to use the tool gun option.
Example 1: To force it to play kylo ren's extinguishing sound, we set SWEP.UseOffSound = "lightsaber/kylo_off.wav"
Example 2: To use the tool gun option, we set SWEP.UseOffSound = false
Entry: SWEP.UseSecHilt = "STRING" || false
Description: The same as SWEP.UseHilt, but for the off-hand ( left hand ) lightsaber of a dual wield lightsaber weapon. Does nothing for single lightsaber weapon.
Entry: SWEP.UseSecLength = NUMBER || false
Description: The same as SWEP.UseLengtht, but for the off-hand ( left hand ) lightsaber of a dual wield lightsaber weapon. Does nothing for single lightsaber weapon.
Entry: SWEP.UseWidth = NUMBER || false
Description: The same as SWEP.UseWidth, but for the off-hand ( left hand ) lightsaber of a dual wield lightsaber weapon. Does nothing for single lightsaber weapon.
Entry: SWEP.UseSecColor = Color( NUMBER_RED, NUMBER_GREEN, NUMBER_BLUE ) || false
Description: The same as SWEP.UseColor, but for the off-hand ( left hand ) lightsaber of a dual wield lightsaber weapon. Does nothing for single lightsaber weapon.
Entry: SWEP.UseSecDarkInner = NUMBER || false
Description: The same as SWEP.UseDarkInner, but for the off-hand ( left hand ) lightsaber of a dual wield lightsaber weapon. Does nothing for single lightsaber weapon.
Section Six: Creating Custom Lightsabers (Part C)
You can also overwrite the form settings in the sh_swlwos file to give a lightsaber a particular set of forms/stances despite the user not being of the appropriate usergroup. This is useful for creating training sabers of particular forms and stances, or separating forms by jobs. I have put this in a separate section so I can show plenty of examples.
Entry: SWEP.UseForms = {
[ "STRING FORM NAME 1" ] = { NUMBER_STANCE1, NUMBER_STANCE2, ... },
[ "STRING FORM NAME 2" ] = { NUMBER_STANCE1, NUMBER_STANCE2, ... },
. . .
}
Description: Do we overwrite the user group settings defined in sh_swlwos.lua and instead make the lightsaber have these forms / stances available? For STRING FORM NAME entries, check the form names in the "lua/wos/advswl/config/sh_swlwos.lua" file. Remember to put a comma after every FORM entry line, and a comma after every STANCE. DUAL WIELD FORMS WILL NOT WORK ON SINGLE LIGHTSABERS AND VISA VERSA! If we want to use the restrictions set in that file, set it to false.
Example 1: If we want to set a lightsaber to have the stance 2 and 3 of the Defensive form, we set the entry as follows:
SWEP.UseForms = {
[ "Defensive" ] = { 2, 3 },
}
Example 2: If we want to set a lightsaber to have all stances of the Defensive form, and stance 1 and 3 of the Aggressive form, we set the entry as follows:
SWEP.UseForms = {
[ "Defensive" ] = { 1, 2, 3 },
[ "Aggressive" ] = { 1, 3 },
}
Example 3: If we want to set a lightsaber to have the stance 1 of Defensive, stance 2 of Aggressive, and stance 3 of Versatile we set the entry as follows:
SWEP.UseForms = {
[ "Defensive" ] = { 1 },
[ "Aggressive" ] = { 2 },
[ "Versatile" ] = { 3 },
}
Example 4: If we want to set a lightsaber to have stance 2 of the Arrogant form ( DUAL WIELD ONLY ) we set the entry as follows:
SWEP.UseForms = {
[ "Arrogant" ] = { 2 },
}
Example 5: If we want to use the restrictions given by the sh_swlwos.lua file, we set
SWEP.UseForms = false
In general you can replace the form string by the name of any form you create, and the stance by whatever stance number you choose.
Section Seven: Creating Custom Forms and Stances
As of the Perception Update, forms and stances can be made as you choose with any animations! The Calm of Fate update has since refined this concept, making it extremely easy to make your own forms.
You should create a form file in the lua/wos/advswl/forms folder.
Example file path would be
addons/ADDON_FOLDER_NAME/lua/wos/advswl/forms/EXAMPLE_FORM.lua
The template file for form creation is as follows:
local FORM = {}
FORM.Name = "EXAMPLE FORM"
--Who does this form belong to? Options: FORM_SINGLE, FORM_DUAL, FORM_BOTH
--These are enumerations for their respective area.
--FORM_SINGLE can only be used by single wielded sabers
--FORM_DUAL can only be used by dual wielded sabers ( one in each hand )
--FORM_BOTH can be used by either wielding technique
FORM.Type = FORM_SINGLE
--What user groups are able to use this form? And which stances?
--FORMAT:
--["USERGROUP NAME"] = { STANCE1, STANCE2, STANCE3, ... ),
--DO NOT FORGET COMMAS AFTER EACH USERGROUP ENTRY!
--DO NOT CREATE FORMS THAT
FORM.UserGroups = {
["superadmin"] = { 1, 2, 3 },
}
FORM.Stances = {}
FORM.Stances[1] = {
[ "run" ] = "",
[ "idle" ] = "",
[ "light_left" ] = {
Sequence = "",
Time = nil,
Rate = nil,
},
[ "light_right" ] = {
Sequence = "",
Time = nil,
Rate = nil,
},
[ "light_forward" ] = {
Sequence = "",
Time = nil,
Rate = nil,
},
[ "air_left" ] = {
Sequence = "",
Time = nil,
Rate = nil,
},
[ "air_right" ] = {
Sequence = "",
Time =nil,
Rate = nil,
},
[ "air_forward" ] = {
Sequence = "",
Time = nil,
Rate = nil,
},
[ "heavy" ] = {
Sequence = "",
Time = nil,
Rate = nil,
},
[ "heavy_charge" ] = "",
}
wOS:RegisterNewForm( FORM )
The stance formatting in detail can be described with the following:
Entry: FORM.Name = "STRING"
Description: This is the name of the form and will appear in the Form Selection menu as well as be used as an identifier. DO NOT USE THE SAME FORM NAME FOR ANY OTHER FORMS!
Example: If we want the form to be called Example Form, we would set
FORM.Name = "Example Form"
Entry: FORM.Type = FORM_SINGLE || FORM_DUAL || FORM_BOTH
Description: This is the type of wielding technique that can use this form. Their enums are fairly straight forward, but SINGLE is for a single saber, DUAL is for dual wielding ( one in each hand ) and BOTH uses each one.
Example: If we want the form to be available to both types of users, we would set
FORM.Type = FORM_BOTH
Entry: FORM.UserGroups = {
[ "STRING USERGROUP 1" ] = { NUMBER_STANCE1, NUMBER_STANCE2, ... },
[ "STRING USERGROUP 2" ] = { NUMBER_STANCE1, NUMBER_STANCE2, ... },
...
}
Description: This is how you restrict the form and it's stances to particular user groups. User groups are case sensative so be careful who it's inputted. Also, only include stances that you have made for the form, or you will experience errors.
Example 1: If we want to set the "superadmin" user group to have the stance 2 and 3 we set the entry as follows:
FORM.UserGroups = {
["superadmin"] = { 2, 3 },
}
Example 2: If we want to set the "VIP" and "owner" user group to have the stance 1-3 we set the entry as follows:
FORM.UserGroups = {
["VIP"] = { 1, 2, 3 },
["owner"] = { 1, 2, 3 },
}
Entry: FORM.Stances[ NUMBER_STANCE ] = { TABLE DATA }
Description: This is how you will create stances for the form. You should be copying the template stance and changing the number stance based on what stance you want that data for. Increment the number up every time you add a new one, and never go below 1. The general format you will be seeing within is
[ "TYPE OF ATTACK" ] = {
Sequence = "SEQUENCE STRING",
Time = TIME THE ANIMATION WILL PLAY,
Rate = HOW FAST THE ANIMATION WILL PLAY,
},
Sequences should be obtained from the wiltOS Viewer widget that comes with the wiltOS Animation Base
The Time should be an integer value in SECONDS. nil = Use default sequence time
The Rate should be a decimal value. 0.5 = Half Rate, 2 = Double Rate, nil = Use default sequence rate
You should not be adding new types of attacks, instead use the pre formatted entries from the example or you will see errors!
Here I will reference the AGGRESSIVE stance so it's clear to see how it works:
local FORM = {}
--The name of this form. Do not repeat names of forms!
FORM.Name = "Aggressive"
--Who does this form belong to? Options: FORM_SINGLE, FORM_DUAL, FORM_BOTH
FORM.Type = FORM_SINGLE
--What user groups are able to use this form? And which stances?
FORM.UserGroups = {
["user"] = { 1 },
["jedi"] = { 1, 2, 3 },
}
FORM.Stances = {}
FORM.Stances[1] = {
[ "run" ] = "phalanx_r_run",
[ "idle" ] = "phalanx_r_idle",
[ "light_left" ] = {
Sequence = "phalanx_r_left_t3",
Time = 0.5,
Rate = nil,
},
[ "light_right" ] = {
Sequence = "phalanx_r_right_t3",
Time = 0.7,
Rate = nil,
},
[ "light_forward" ] = {
Sequence = "phalanx_r_s1_t2",
Time = nil,
Rate = nil,
},
[ "air_left" ] = {
Sequence = "phalanx_a_left_t1",
Time = 0.6,
Rate = 1.6,
},
[ "air_right" ] = {
Sequence = "phalanx_a_right_t1",
Time = 0.6,
Rate = 1.7,
},
[ "air_forward" ] = {
Sequence = "phalanx_a_s1_t1",
Time = 0.6,
Rate = 1.2,
},
[ "heavy" ] = {
Sequence = "phalanx_b_s1_t1",
Time = 2.0,
Rate = 0.5,
},
[ "heavy_charge" ] = "phalanx_b_s4_charge",
}
FORM.Stances[2] = {
[ "run" ] = "phalanx_b_run",
[ "idle" ] = "phalanx_b_idle",
[ "light_left" ] = {
Sequence = "phalanx_b_left_t3",
Time = 1.0,
Rate = nil,
},
[ "light_right" ] = {
Sequence = "phalanx_b_right_t2",
Time = 0.7,
Rate = nil,
},
[ "light_forward" ] = {
Sequence = "phalanx_b_s2_t3",
Time = 0.8,
Rate = nil,
},
[ "air_left" ] = {
Sequence = "phalanx_a_left_t1",
Time = 0.6,
Rate = 1.6,
},
[ "air_right" ] = {
Sequence = "phalanx_a_right_t1",
Time = 0.6,
Rate = 1.7,
},
[ "air_forward" ] = {
Sequence = "phalanx_a_s1_t1",
Time = 0.6,
Rate = 1.2,
},
[ "heavy" ] = {
Sequence = "phalanx_b_s1_t1",
Time = 2.0,
Rate = 0.5,
},
[ "heavy_charge" ] = "phalanx_b_s4_charge",
}
FORM.Stances[3] = {
[ "run" ] = "phalanx_h_run",
[ "idle" ] = "phalanx_h_idle",
[ "light_left" ] = {
Sequence = "phalanx_b_s2_t1",
Time = nil,
Rate = nil,
},
[ "light_right" ] = {
Sequence = "phalanx_h_right_t1",
Time = nil,
Rate = nil,
},
[ "light_forward" ] = {
Sequence = "phalanx_h_s1_t1",
Time = 1.2,
Rate = nil,
},
[ "air_left" ] = {
Sequence = "phalanx_a_left_t1",
Time = 0.6,
Rate = 1.6,
},
[ "air_right" ] = {
Sequence = "phalanx_a_right_t1",
Time = 0.6,
Rate = 1.7,
},
[ "air_forward" ] = {
Sequence = "phalanx_a_s1_t1",
Time = 0.6,
Rate = 1.2,
},
[ "heavy" ] = {
Sequence = "phalanx_b_s1_t1",
Time = 2.0,
Rate = 0.5,
},
[ "heavy_charge" ] = "phalanx_b_s4_charge",
}
wOS:RegisterNewForm( FORM )
