NOTE: If you can't find the answer to your question here, feel free to or ask a question in our friendly Community Forum or search the Manual. You may also be able to find what you're looking for in the Knowledge Base Articles. .


CONTENTS

  1. About
  2. Upcoming Versions
  3. Upgrading
  4. Feature Questions
  5. Compatibility
  6. How-To
  7. Bugs & Troubleshooting
  8. License

ABOUT

What is UFPS?
UFPS (Ultimate FPS) is a next-gen first person framework featuring physics-based animation of first person controllers, cameras and weapons. It generates super smooth and natural animations in realtime based on player input and external physics forces.

Hundreds of parameters can be used to manipulate the camera and weapon model, allowing for a vast range of complex, realtime-generated behaviors. Tweaking is fun and often yields cool and unexpected results. To see UFPS in action, check out our YouTube Channel or try this online demo.

Who makes it?
VisionPunk, a small team of hardcore indie game developers headed by Calle Lundgren - some with many years previous experience in shipping AAA action games. Our mission is to put amazing tools in the hands of small teams, allowing them to compete on entirely new levels of quality.


UPCOMING VERSIONS

When will the next version be released?
What are the confirmed features of the next version?

Up-to-date information on upcoming features is available HERE.


UPGRADING

How do I upgrade the system to the latest version?

IMPORTANT: Never update UFPS without backing up your project and deleting the previous UFPS folder. Simply overwriting the previous folder will not work and could break your project. Modifications to UFPS should ideally be made using script inheritance in a folder outside the UFPS folder. For more info, see the following sections.

Upgrade Instructions

  • If you purchased the asset from Unity Asset Store:

    1. Always begin by backing up your existing project and reading the latest Release Notes.
    2. Start Unity. You may want to create a clean project for the initial install.
    3. Open Asset Store by clicking "Window -> Asset Store" at the top main menu.
    4. At the bottom right of the main store screen, click "My Stuff -> See complete list".
    5. In the screen that opens, locate UFPS and click the "Update" button.
  • If you purchased the asset from visionpunk.com:
    When you purchased the asset, you received an email from VisionPunk Support, titled "Your UFPS : UFPS File Download". Locate this email and click the link to download the latest version. It is a good idea to make a backup of this link for making future upgrades.

    NOTE: We previously used a service called bytecommerce, which has seized operation. If you ordered using bytecommerce please contact us to upgrade and we will move you to the new system:


I can't find my asset in the Asset Store Download Manager ("My Stuff") section. What's up?
Don't worry. You still have your license. We sometimes (if rarely) unlist an asset from display in the Asset Store. This is necessary when we don't wish to distribute more copies of it at the present moment, for example - due to support workload, refactoring, rebranding or relaunching. Unfortunately, unlisting an asset from display in the storefront means it also becomes invisible to existing users. This is a limitation of the Unity Asset Store. Please contact us with your invoice number and we'll get you a download link.


I have modified the source files. Will my changes be overwritten if I upgrade?
YES! You changes will be overwritten. Always backup and delete your UFPS folder before upgrading. It is generally a very good idea to also carefully read the Release Notes.


How to modify the system in such a way that it can be upgraded later?

  • If you're in a hurry and just want to play around with minor tweaks you might want to use the same comment tag, for example "// TEST" wherever you make a change. Backup your file before upgrading and match the modified spots later by doing a "Find All" in your backed up file.

  • If you are planning heavy modifications to UFPS classes, it is best to create your own scripts derived from (inheriting) the existing ones (as opposed to editing the scripts directly). Many methods and parameters in the UFPS classes are protected instead of private in order to facilitate this. For more info on inheriting classes, see this tutorial on inheritance in C#.
  • Preferably keep your inherited classes in a folder outside the UFPS folder. This way, your own changes will always be left untouched and the underlying base type will be upgraded separately - i.e. you won't have to manually restore your changes on a line-per-line level. If the new asset version breaks your code, the error messages should be more clear and it will be a lot easier to repair things.
  • If you're lucky both the upgrade and your modifiations are coded in such a way that there will be a minimum of havoc.
  • Please note that UFPS is still very much in construction and is frequently overhauled so it may be a while until updates run smoothly.


FEATURE QUESTIONS

Does UFPS support mobile / touch?
We have an experimental mobile add-on going, available as a standalone package for iOS and Android. Although please note that this is a side-project that we maintain only sporadically. It has not been optimized, and does not support low- or mid-end phones. For more info see the Mobile Add-on for UFPS.

Does UFPS support networking / multiplayer?
The "UFPS & Photon Multiplayer Starter Kit" is in active development and due for release in 2014. Right now there is no built-in multiplayer support. If you're in a hurry, you may be able to add your own multiplayer functionality or use a third-party asset. Depending on your skill level and choice of network solution multiplayer can be added in different ways. Check out Photon Unity Networking. For the latest info on multiplayer progress, see this forum thread.

How modular / expandable is the system?
A lot of effort has gone into keeping the asset as generic and modular as possible. You should be able to use it for anything that needs a player in 3d space with a first person view. If you don't want a certain feature it should be easy to take out (v1.4 was a big leap in this direction), and the asset should stay reasonably compatible with other assets.

Where can I find more weapons?
There are plenty of weapon assets in the Unity Asset Store. If you can't find what you're looking for try TurboSquid. With UFPS it should be very easy to hook up pretty much any weapon model. It doesn't matter whether it has animations or not. UFPS will animate it for you. For more info on setting up weapon models in your 3d art package, see this answer and this manual chapter.

Does the controller use realistic physics?
The controller uses its own physics simulation with a number of sliders for manipulating ground friction, air speed and such. It also reacts to external forces, such as explosions, and has simple logic for wall deflection. All of this was overhauled and improved in v1.4.0. However, although it plays along well with external rigidbody objecs, it is no "realistic" physics simulation. It just has a number of parameters allowing you to tweak it for "fun" physics.

Why is this particular feature not implemented like the one in game X?
Will you add my feature idea?

Here's the policy on new features: Most developers use UFPS for shooters. A few want hard core realism, a lot of people want to make mobile games and some want crazy old school FPS gameplay with cartoony physics (someone even took out the guns and used it to build an online 3D shop). Since most users do want weapons gameplay there is lots of functionality for that. But we are trying to stay away from specific FPS genres since it narrows down the user base significantly.

In short: the likelihood of any one feature to be included will increase if it's generic enough to be shared among several different first person gameplay types, platforms, settings and genres (arena deathmatch, fantasy, sneaker, military, mobile, puzzle etc.).



COMPATIBILITY


PLEASE NOTE:
  • UFPS : Ultimate FPS was designed for the Windows and Mac OS X target platforms. No other platforms are guaranteed to work, nor supported, and should UFPS work on them it's a happy accident.
  • Mobile Add-on for UFPS (standalone product) can be built to iOS and Android platforms.

Unity 3.x
UFPS is no longer guaranteed to work in Unity 3.x.

Unity 4.x
UFPS requires atleast Unity 4.6.2. If you connect to the Asset Store using Unity 4.x, you will get the Unity 4 version of UFPS. Note that this version has not been adapted to work on Unity 5.


Unity 5.x

UFPS exists in a special version for Unity 5, and you will get it automatically if you connect to the Asset Store using Unity 5.x.

Unity Personal / Free
Works fine (note that on Unity 4, the manual chapter on Image effects is only applicable to Unity Pro).

Unity Pro
Works fine.

Unity iOS / Android
Basic touch / mobile support is available as a paid Mobile Add-on for UFPS. Note that only input and GUI is affected and the game engine is not optimized for mobile. Player body systems are not supported, for example. Also, see this answer.


VR / Oculus Rift

UFPS was designed for desktop play, and there are not yet any VR-exclusive features in the code. Note that plain UFPS may have too wild camera motions for VR and you will have to adjust your game accordingly. Player body systems may not be suitable for VR. Our adventures in VR are just getting started.

Unity Flash
UFPS does not work with the Flash exporter. It's probably possible to get it up and running but you need to be adept at finding the causes of the build problems. As for performance: no idea.

UniStorm
Works, with some tweaking. See these posts for more info:

Other Asset Store assets
The ambition is to have UFPS co-existing and fully compatible with most other assets, though this is challenging given the diversity of Unity Assets. Usually when there are rendering issues it has something to do with the dual camera setup. Try disabling the "WeaponCamera" object in your FPSPlayer and see what happens (it is possible to run UFPS with only the main camera and v1.4 introduces a new weapon retraction system to deal with the weapon intersecting scene objects when running in this mode). Let me know if you discover any issues preventing UFPS from co-existing with another Unity system.



HOW-TO

How to make the controller walk on moving platforms?
UFPS has advanced moving platform support with several different movement patterns and modes of operation. See the manual chapter HERE.

How to enable the mouse cursor by pressing Enter, like in the demo?
You need to toggle the "MouseCursorForced" property of vp_FPInput.

How to make a "progressive" jump instead of an "impulse" jump, like in Mario or Quake?
UFPS has an advanced jumping implementation with lots of fine control over the jump experience. For example, you can have it accumulate jump speed while holding the button. See the manual chapter about the controller for more info.

How to to add my own weapons?
Adding a custom weapon model is very easy. Just drag the model into the FPSCamera hierarchy in a couple of easy steps (see the manual chapter "Creating an FPS player from scratch -> Adding a weapon"). It should work pretty much instantly. The included weapon motion / gameplay presets are not specific to any one weapon model. That is: a preset file designed for a pistol should work on most pistol models.

If you put the model at the exact same spot and roughly the same scale as in our demo gun scenes, the demo motions should work fine for you. Note that the reload motion for the pistol is a bit special and you should read the comments in the method 'DoExamplePistolReloadSequence' of the file 'vp_FPSDemo2.cs' for instructions on how to use it in your own project.

How should weapon models be positioned in my 3D art package?
The weapon should be rotated straight forward with no rotation around the X or Y axis (otherwise the iron sights won't match up by default when zooming). You can set the ingame position and rotation (aswell as the pivot) in the Inspector and in the preset scripts, so that doesn't really matter, but in general we recommend to keep the weapon 100% centered in the X axis, roughly centered in the Y axis and to keep the elbow of the arm at about the center of the Z axis. This way you'll make sure the weapon will be visible by default when added to the FPSPlayer, simplifying further editing. If you will be making many weapons, this rough placement is a good standard to conform to. Final tweaking of position and rotation should be done on the FPSWeapon component in the Inspector.



Click to scale up

One important point is that any arm geometry should be positioned so that an imaginary tube (about 3 inches in diameter) would be able to pass from the top of the wrist to the camera plane without touching any arm geometry. If it does, you will have trouble with the camera clipping arms ingame at some point (we call this the Pringles Tube Rule).

How to implement ladders?
Ladder functionality is now included in UFPS. See this manual chapter.

How to make the character slide on steep terrain?
An advanced sliding feature was added in v1.4.

How do I find a certain preset that I liked from the demo?
The root Presets folder only contains a few standard generic FPS motion patterns. The "Demo/Presets" folder contains all sorts of experimental motions. For example, the files used for the Astronaut example are:


        AstronautCamera.txt
        AstronautController.txt

The demo (vp_FPSDemo.cs) loads these kind of "brute force" onto the FPSController and FPSCamera components. However, since version 1.3 there is a new state system that you can use to assign the presets in the editor with little or no need for scripting. For more information about this, see the chapters "Presets" and "States" in the manual.

How to change the controls?
UFPS has a very powerful Input Manager which can rebind the controls at runtime (not possible in standard Unity). See this manual chapter.

How do I get world shadows to affect the weapon?
Check out this post. Also, the next version of the asset, v1.4, will greatly simplify running the system without a weapon camera (allowing better weapon shadows), along with features to prevent the weapon from intersecting objects.

How to limit ammo clips?
The latest v1.4 has new ammo clip and ammo type logic.

How to switch between 1st and 3rd person cameras?
UFPS 1.4.8 introduced a 3rd person view. Please see the 1.4.8 release notes for more info.

How to make the camera fly / have a spectator mode?
The UFPS controller has a Free Fly mode, which can be used to implement zero gravity, spectator mode and so on. See this manual chapter.

How to display the full player body?
UFPS 1.4.8 introduced various advanced player body features, including "full body awareness". Please see the 1.4.8 release notes for more info.

How to fire a projectile using physics?
The shooting class works by simply spawning a Unity gameobject. So if you put a grenade model in the projectile slot and press fire it will spawn a grenade hovering in mid air. If the grenade has rigidbody physics applied it will fall down. If the grenade has a script that sets some velocity on it in its Awake method, it will fly away from the shooter in a desired direction. So you see it is very open ended and with a little C# scripting and knowledge of the Unity scripting methods you can do pretty much what you want.

The included bullet class uses a hitscan, which means the bullet impact occurs instantly. If you want more realistic ballistics simulation you could modify the bullet script (or just create a new one) to spawn an actual model with physics on it and set velocity. The Ageia physics engine in Unity has some issues with tiny, fast moving projectiles not colliding properly, but we suspect there are quite a few forum threads discussing solutions to this.

How to do bullet penetration?
We haven't implemented bullet penetration into UFPS yet, but several people have asked this question before so there has been some discussion on it. You may have already seen these posts, otherwise you may find them useful:

How do I give or take weapons away from the player?
How to handle inventory (access to weapons, items, ammo etc)?

Every weapon the player should potentially be able to carry must first be added as children to the FPS camera. Then add a vp_PlayerInventory component to the player. Without one, the player happily has access to all weapons childed under the camera. Please see the manual Inventory chapter for more info.

With an active inventory component, the UFPS event system will intercept all calls to switch weapons and make sure you're allowed to. If the "Have" parameter for a weapon entry is initially set to zero, the player starts without the weapon. To learn how all this works in scripting, study the event system manual chapter ... Also, you may want to study how the vp_SimpleInventory script and the various pickup scripts talk to the event system.

How do I add melee animations?
v1.4 included a beta of a really cool new melee system for swinging the weapon model around. If you want to do things "inside" the weapon model, such as stabbing, parrying or slashing (bending an arm or fingers) you have to use a model with animations (this is also true for pistol / rifle reload animations). So for a melee attack it would work like in any Unity game: make sure your weapon model has an attack animation, then trigger it from script when the user attacks. Please note that melee is not yet well supported in 3rd person.

How to do melee damage?
The melee system in v1.4 has it's own damage zone logic. See the manual for more info.

How to add/sync animations?
For playing animations on weapons the simplest way is to use the regular (legacy) Unity animation system. The weapon related classes in UFPS have hooks to play simple animations like Fire, Reload, Idle etc. For syncing motion with animations, check out 'Step Threshold' in the manual. This functionality is used to execute a method in sync with the bob. You can use this to sync animations or atleast calculate the appropriate rates. The mech example in DemoScript uses this.

How to wield multiple weapons at the same time (akimbo)?
This will very likely be supported in a future version. If you want to have a go at it yourself, here's a hint: Weapon switching logic in UFPS basically works by hiding all weapon models and then reenabling a single one. The WeaponHandler class must be rewritten to manage more than one weapon at a time.



BUGS & TROUBLESHOOTING

My game crashes. Why?
When Unity crashes it displays an error message in the console bar at the bottom left of the screen. Click on the icon to open the console. A window opens showing a list of any and all errors. Note that the last error displayed may not be the one that caused Unity to become unstable. To find the real source of the crash, you must often look further up the error list. The first (red) error message is often the culprit. Finding the name of the script and the line number of the crash in this way will often lead to "AHA!" moments.



I am seeing multiple weapons at once
All the weapons showing at once is usually what happens if the system crashes before or during startup and the 'SetWeapon' method hasn't had a chance to run yet (to hide the unused weapons), either that or SetWepon itself crashes. Nine times out of ten when this happens there is a "NullReferenceException" error message in the console, caused by some other code.

I have trouble with the "Dual Joysticks" example from Unity Standard Assets
The joystick example script uses GUITextures, which require a GUILayer component to render. Some people have been confused by this. In order for it to draw the GUI, you must add a GUILayer component to your FPSCamera and it should work.

I have trouble getting this to work with GUIText
Note that GUIText is the oldest Unity gui class. We'd recommend instead using UnityGUI, or even better NGUI. However, if you still wish to use GUIText, We've had a few people who were having problems with this and they had forgotten to add a GUILayer component. That is: for the GUI to be drawn, a GUILayer component must be added to your FPSCamera and it should work.

I have trouble making the camera show flares
You may have to add a Flare Layer component to the FPSCamera gameobject.

The pistol reload animation is only partially played if there is no 'Demo' object
Correct, the pistol animation is entirely scripted and is a demo example, intentionally "hidden away" in the vp_FPSDemo2.cs script since it's not the recommended way of doing more complex weapon animation. Quoting the script comment:

"This is just an example of how you can play around with states and timers to create animations. NOTE: this is provided just as an example. It is not the recommended way of doing things: any complex animation such as a pistol reload sequence should be done using a regular animation on the pistol mesh. If you want this method in your actual game project (not really recommended), copy it into your player script along with its reference in 'Update'"

Bullet holes appear on my enemy colliders
To change this, edit the file 'vp_Bullet.cs' and right after this part:


        // do damage on the target
                hit.collider.SendMessage(DamageMethodName, Damage, SendMessageOptions.DontRequireReceiver);

... add the following:


        if(hit.transform.tag == "enemy")
                TryDestroy();

Now, if you set the tag of your enemy gameobjects to "enemy", the bullet holes should not appear.

I am having a problem with execution order of the Awake calls.

  1. From the Unity main menu, go to "Edit -> Project Settings -> Script Execution Order"
  2. Add the suspected troublemaker script to the execution order by pressing the "+". Do the same for any other involved / custom scripts.
  3. Test how the application behaves depending on which script executes first. Drag to rearrange the scripts. Note that you may also drag a script above the "Default Time", in which case it will execute before all other scripts.

For the reference on execution order look here.


LICENSE

Can I use your asset for commercial purposes?
Yes, you may use the asset for commercial purposes. Your purchase grants a lifetime license with unlimited updates. Short version:

  • You may use the asset in a game or other type of interactive media, for commercial or other purposes.
  • Obviously it is forbidden to lend, license or resell the asset separately or resell any part of its code or content as part of a Unity editor extension.
  • The asset must be included (packed) in your game in such a way that your own end users would have a reasonably hard time extracting its data.
What is the license?

Here's the licensing agreement for assets purchased from Unity Asset Store:
    ASSET STORE TERMS OF SERVICE AND EULA.

    NOTE: If you have any further questions regarding the Unity Asset Store EULA please contact Asset Store Support
    (we didn't write it - Unity's lawyers did :)

Here's the licensing agreement for assets purchased from visionpunk.com:
    VISIONPUNK LICENSING AGREEMENT.

Why is the asset so expensive?
Unity's recommended price range for an advanced scripting asset is $100 - $1000. UFPS is currently priced at $95 with tens of thousands of hours of hard work under the hood. Is it really that expensive?

Can I expect updates?
Since introduced in 2012, UFPS has been updated bi-monthly on average, with hundreds of features added. This represents tremendous value for early adopters. That said, please note that updates are not guaranteed and development of an asset or feature may be halted at any time with no prior notice.

Can I have a refund?
Under the Asset Store EULA, all sales are final. Licensing source code is not like buying physical goods (the source code can not be "returned" to the store in a way that it's no longer in the possession of the buyer). Consider this carefully before licensing any of our assets, as there is no going back.



I have made a mod / feature. Can I post my script for others to use?
Cool! As long as you don't post entire script files from UFPS, feel free to post your modifications in this forum thread. For example:


        ...in function so and so, after the line that says so and so, paste the following:

                // some code

        ... and on the line that says so and so, replace so with yada

Tip: it's a very good idea to use forum code tags ...

  • In the VisionPunk forum: <PRE><CODE> your code </CODE></PRE>
  • In the Unity forum: [CODE] your code [/CODE]
... and to refer to method names instead of line numbers since the numbers might differ for others due to their individual file mods.

We really encourage sharing modifications. It's often helpful to other users and always interesting to see what people are doing with the asset.