Project selection 155
See also : Editor interface overview.
This page is for version v1.5.5
For the latest version of PopcornFX, see: Project selection
For previous versions of PopcornFX, see the following pages:
- 1 Overview
- 2 Projects panel
- 2.1 Opening a project
- 2.2 Creating a project
- 2.3 Removing a project
- 2.4 Project settings
- 2.5 Upgrading projects
- 3 Recent files panel
- 4 Online packages panel
- 5 Auto Updates
When you first start the PK-Fx editor, the following window will pop-up:
This is the project selection window.
It gives you various useful information:
- 1 : Popcorn-SDK version
- 2 : User data-folder path (this is where all the projects in the project list are stored, as well as all your user-specific data)
It is split in 3 main panels:
There are also various buttons to manipulate all this:
- 6 : Show user infos
- 7 : Manually check online for editor updates
- 8 : Quit popcorn editor
- 9 : Launch popcorn editor on the selected project (same as double-clicking on the project)
|Data Folder||Tells the Popcorn-Fx editor where to look for the projects settings.|
It is by default set to a user-directory. You do not have to have your packs in this folder, this is for the user configuration stuff.
|Misc User Infos||For our internal use only, used to notify company-specific upgrades if you have a registered popcorn SDK license.|
Otherwise, just useful for us to get some stats and keep you updated on new popcorn stuff.
|Check For Updates||if this is checked, the editor will check, on startup, if there is a more recent build uploaded on the popcorn servers.|
If there is, it will pop a notification window asking you if you want to upgrade.
PK-Fx Editor allows you to setup multiple "projects" at once. However, you can only have a single project loaded at a single time.
This panel allows you to add new projects, and change their settings.
- 1 : Project name
- 2 : Upgrade project
- 3 : Remove project
- 4 : Create new project
- 5 : Add existing project
- 6 : Show project settings
Opening a project
To open a project, you can either:
- double-click on the project you wish to open
- select the project, and click the 'OK' button in the window's bottom-right corner.
Creating a project
You can either:
- add an existing project
- click on the 'Add' button
- An explorer window will pop and ask you to pick a 'PopcornProject.xml' file that's inside the project you want to add.
- create a new project from scratch : click on the 'Create' button
- Click on the 'Create' button
- An explorer window will ask you to pick a folder inside which the popcorn editor should create the project file.
- This folder does not have to be the project root folder, but MUST be inside the project directories.
- See the Project creation and setup page for more details.
Removing a project
The little garbage-can icon on the left of each project deletes the project's entry in the project list.
It does NOT delete the project's files ! it only removes the project from the list of projects.
Clicking on the 'Settings' button pops-up the project settings window:
General & Coordinate-system setup
The "Pack root" tells the editor where the pack is physically located.
It can be a path relative to the data-folder, or an absolute path.
The Coordinate-system setup panel will allow you to choose between the following coordinate systems:
|Right handed Y-Up axis
( aka. OpenGL )
|Right handed Z-Up axis
( aka. Max )
|Left handed Y-Up axis
( aka. DirectX )
|Left handed Z-Up axis|
In this panel, you can add a list of paths to be excluded from your project hierarchy. This is useful if you have lots of game-data you don't care about when creating effects.
Ignored folders will not be displayed in the content browser.
You can also add a list of paths to be included _on_top_ of the excluded paths.
As these are applied after, if means you can basically:
- exclude the project root
- include only the few FX-related folders
- exclude everything except the few FX-related folders
You can add custom resource paths to where your resources are located, to make them browsable from within popcorn.
(absolute paths are forbidden to reference resources in the editor).
This panel allows you to specify which extensions should be treated as which resources.
Currently, it is only useful if you want to forbid browsing certain filetypes from within the popcorn editor.
For example, you can force the editor to only browse and use .dds files, and not show any of the other image filetypes, by just removing them from the list in the 'Textures' tab.
Here you can setup your list of output platforms to tell the editor where it should output the baked targets for each platform.
See the AssetBaker page for more details
Sometimes, when a new version of the popcorn runtime & editor is released, some things might change that will cause assets to break.
Although the file formats popcorn uses support retro-compatibility, it is on-purpose that we do not make everything retro-compatible.
This gives us much more freedom to improve and refactor things that need to be, to bring you a better system.
However, we have a system that knows the history of breaking-changes in assets, from version to version, and can automatically upgrade yours if they are from an earlier version.
It can only upgrade assets from an earlier version to a newer version, NOT downgrade them from a new version to an old one.
This has various implications:
- Your editor packs must ALWAYS have the "LastRevision.txt" file at their root. This is where the editor stores the last version of the pack. (This might change in the future to add a per-asset version number, to make it easier to transfer assets from one machine to another, that might not have the same editor version)
- If you have popcorn packs in source-control, Make sure their "LastRevision.txt" file is in source-control too, so that the pack won't get upgraded twice by different people.
- You should avoid manually copy/pasting assets from packs that are not upgraded to the same popcorn version.
- Your popcorn editor version should match your runtime version
The editor makes it clear in the project list which projects are out-of date and need updating, by highlighting them in red and displaying a tooltip giving details about what changes have taken place between that pack's version and the current editor version:
Projects without the "LastRevision.txt" file at their root will be treated as legacy packs (before the revision system was introduced), and ALL patches will be applied:
Upgrading a project
To upgrade an out-of-date project, simply click on the 'update' icon appearing next to the 'delete' icon:
This will show the upgrade window, where you can see a detailed list of upgrades, and which ones need to be applied.
Upgrades shown in green are already applied. Upgrades shown in red still need to be applied.
You can choose to upgrade step by step by clicking the small upgrade button next to each upgrade.
Doing so will run all upgraders up to that upgrade included, but will not upgrade further.
Here, we clicked on the 126.96.36.19932 'upgrade' button:
Clicking 'Apply' will upgrade up to the selected upgrade, by default, it will upgrade to the latest upgrade.
When the pack is up to date, the upgrade window will say so:
Troubleshooting project upgrade
Sometimes, a project upgrade can fail.
Most of the time, this is due to the access permissions on the files that the editor tries to upgrade.
It can happen if you are using a source-control software that locks the files and sets them to read-only mode.
The popcorn editor will not force them to read-write, therefore will fail upgrading them if they are read-only.
If anything goes wrong during the upgrade, it will be logged in the 'Errors' output panel underneath the list of upgrades:
You can also take a look at the 'Infos' output panel to see which files were touched during the upgrade, which will tell you exactly which files have failed, and why:
You might also get this error when upgrading:
Which indicates the editor failed writing to the "LastRevision.txt" file at the root of the PopcornFx pack.
Projects more recent than the editor
A project MORE RECENT than the editor will appear in a slightly deeper red, and the tooltip will say so explicitely:
Trying to open the project will pop up the following warning window:
Recent files panel
This lists the recent files of each project, and allows you to select what file should be automatically opened when launching the project.
- 1 : if cheched, opening the project will also automatically open the file that's selected in the list below
- 2 : list of recently opened files
Online packages panel
The online-packages panel replace the previous version's 'default-packs' that were added by default on each new install.
It shows various Fx packages available online on our servers, that you can download.
You can then either import the package content inside one of your already-existing project, or create a new project from this package.
- 1 : Package description
- 2 : Download progress. Here, already downloaded. If the package has been updated online, the progress-bar will appear empty again, and you will be prompted to re-download.
- 3 : Download / Import button. When not downloaded, will download. Once downloaded, will import the package into the selected project in the project-list.
- 4 : Package thumbnail. Clicking on it will create a new project from this package, prompting you to select the directory inside which you want the project to be created.
The popcorn editor will automatically connect to the popcornfx website to check if there are editor updates/fixes available.
If updates are found, it will display the latest update changelog:
We recommend you keep this check active to get the latest bugfixes. However, if you are bound to an older version of the C++ SDK, you might not want to get the latest editor update, as it may have features not supported by your older SDK.
To disable auto-updates, uncheck the 'Check For Updates' checkbox in the User infos window