Project selection 155

From PopcornFX
Jump to navigation Jump to search

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:


When you first start the PK-Fx editor, the following window will pop-up:

Popcorn-Fx project selection

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)

User infos

Popcorn-Fx Use infos

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.
Make sure you enter a valid email so you'll get the popcorn-fx newsletter. Don't worry, we only send mails for new versions, we won't spam you :)

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.
If you disable this automatic check, you can always check by hand by clicking the "Check Updates" button in the main project selection window.

Projects panel

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.

Popcorn-Fx Project panel

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.

Project settings

Clicking on the 'Settings' button pops-up the project settings window:

General & Coordinate-system setup

Popcorn-Fx general project 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:

Popcorn-Fx coordinate system : right-hand Y up (OpenGL)
Popcorn-Fx coordinate system : right-hand Z up (Max)
Popcorn-Fx coordinate system : left-hand Y up (DirectX)
Popcorn-Fx coordinate system : left-hand Z up
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

Include/Exclude paths

Popcorn-Fx include/exclude paths

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

instead of:

  • exclude everything except the few FX-related folders

Resource paths

Popcorn-Fx resource paths

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).

Resource extensions

Popcorn-Fx resource extensions

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.

Bake targets

Popcorn-Fx bake targets

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

Upgrading projects

Out-of-date projects

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:

Popcorn-Fx project selection : project versions patch summary

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:

Popcorn-Fx project selection : projetc versions patch summary

Upgrading a project

To upgrade an out-of-date project, simply click on the 'update' icon appearing next to the 'delete' icon:

Popcorn-Fx project selection : update project

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.

Popcorn-Fx project upgrade : main upgrade window

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 'upgrade' button:

Popcorn-Fx project upgrade : main upgrade window

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:

Popcorn-Fx project upgrade : main upgrade window

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:

Popcorn-Fx Project upgrade failure

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:

Popcorn-Fx Project upgrade infos

You might also get this error when upgrading:

UpgradeProject Failed 1.png

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:

Popcorn-Fx project selection : project more recent than editor

Trying to open the project will pop up the following warning window:

Popcorn-Fx project selection : project more recent than editor 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.

Popcorn-Fx Recent-files panel

  • 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.

Popcorn-Fx Online packages panel

  • 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.

Auto Updates

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