Project Management¶

Project Creation Wizard¶

The tool for creating new projects is included in the Project Management app and executed by the [Create New Project] button on the main page of this app.

The [Back to Projects] button can be used to return to the Project Manager’s main page, while the [Help] button can be used to access the Help file.

1. Project name is used to name project directories such as “projects/project_name”, “projects/project_name/assets”, “projects/project_name/blender” and “projects/project_name/build”.

2. Project title as shown in the browser.

3. Project author’s name.

4. Add application templates. Standard application templates: html file, css file, js file will be added to the project directory “projects/project_name”.

5. Add scene templates. Standard json file will be added to the “projects/project_name/assets” directory; blend file will be added to the “projects/project_name/blender” directory.

6. Use Material Library. Blend files of the material library will be copied to the project directory “projects/project_name/blender”, while the asset files will be copied to “projects/project_name/assets” folder.

7. Copy project manager script. The project.py script will be copied to the project directory.

8. Project’s type. Several options are available:

   • Copy - engine files will be directly copied from the deploy/apps/common/ to the application folder.

     When the project is deployed, only application files are compiled, while engine files are left intact (so you cannot modify the engine itself);

   • Compile - engine sources are compiled with application scripts.

     This option can be used to modify the code of the engine itself;

   • Command - this project type is similar to Compile, but it also gives you an option to set command for compiling the application. Environment variables are also supported.

     Note

     Variables like NODE, NPM or PYTHON refer to the corresponding files in the Blend4Web SDK.

   • None - Project Manager will not copy the engine files to the application folder, nor will it perform any operations upon building the application. Application developers will have to manually perform everything they need;

   • Web Player JSON - json-file placed inside the project is run with the help of web-player inside SDK;

   • Web Player HTML - project is packed into single html-file, containing all required resources.

9. Javascript optimization level.

   • “Simple” - variable names are replaced in the code;
   • “Advanced” - code optimization is performed;
   • “Whitespace Only” - only whitespaces are removed from the code.

10. Web Player URL attributes. This tab is available only if Engine Binding Type parameter is set to Web Player JSON or Web Player HTML.
    • “Show FPS” is used to display the FPS counter in the player’s top right corner.
    • “Auto-rotate camera” enables automatic camera rotation just after the scene loads.
    • “Disable social network buttons” disables social networks buttons on the control panel.
    • “Background transparency” enables transparency for the rendering area.
    • “Use compressed textures” enables loading of minified and compressed textures (in DDS format).
    • “Use compressed textures pvr” enables loading of minified and compressed textures (in PVR format).
    • “Use min capabilities” makes Web Player run application as if it was running on a low-end system (on a mobile device, for example).
    • “Use gzip compression” enables using gzip compression.

Creating a Web Player Application¶

The main advantage of Web Player applications is the ease of deploying such applications on a website.

Creating a Web Player application is simple. All you have to do when creating a new project is select the Web Player JSON or Web Player HTML option under the Application Type tab.

The parameters that are available for a Web Player project are mostly the same as for any other type of project. The only exception is the group of parameter known as the Web Player Params.

Project Settings¶

This panel is only available if the Web Player JSON or Web Player HTML option has been enabled. The parameters listed here are in essence URL attributes that the Web Player application will use while running the project.

Project Information¶

This page contains information regarding the selected project and can be viewed by the [info] link beside the project’s title.

Project Editing¶

A simple web-based interface for editing project files is available by the [edit] link beside the project’s title.

The left part of the editor window contains a list of all .html, .css and .js files from the project directory (projects/my_project). The right part contains the content of a currently selected project file (no file is selected by default) with highlighted syntax.

New .html, .js and .css files can be added to the project directory by clicking the [New File] button.

The [Save] and [Save As...] buttons that can be found at the bottom of the page are used for saving currently selected project file.

Project Config¶

This is a web interface that allows the developer to view and change project settings after the project is created.

This page include all settings available during project creation along with some additional parameters. Some of the parameters are read-only (and thus cannot be changed after the project is created).

Project Import¶

Tools for importing projects are available by the [Import Project(s)] link.

Clicking this link opens standard Open File dialog where you can select the project you need to import.

Project Export¶

Project exporting window can be accessed by the [Export Project(s)] link.

Deploying the Project¶

After you have completed your project, select the deploy project option from the Operations panel on the Project Manager main page. The project will be exported and packed into a single archive.

After that, this archive can then be downloaded by to the folder where your web browser stores all downloaded files by pressing the Download button. It should be noted that the process of downloading can take a significant amount of time depending on the size of the archive.

To place the project on a webpage, you have to extract this archive and upload its files to a web server using FTP, SSH or any other protocols supported by the server.

A Web Player HTML application can then be placed on any webpage by using an iframe container. Here is an example of HTML code that can be used for this:

<!DOCTYPE html>
<html>
<head>
    <title>An Example Application</title>
</head>
<body>
    <iframe width="800" height="500" allowfullscreen src="/projects/myproject/myproject.html"></iframe>
</body>
</html>

Deploying a JSON project is performed similarly, but instead of a single HTML file it uses a combination of the Web Player app and a JSON file that contains the actual scene.

<!DOCTYPE html>
<html>
<head>
    <title>Another Example Application</title>
</head>
<body>
    <iframe width="800" height="500" allowfullscreen src="/myproject/webplayer.html?load=/projects/myproject/myproject.json&show_fps"></iframe>
</body>
</html>

Dependencies¶

The project management system works in all operating systems. However, some operations can require installing additional dependencies. In order to check whether all dependencies are met, use the following command:

./project.py check_deps

For MS Windows users:

python project.py check_deps

For script operation it’s required to install java and set the PATH system variable.

Resource Converter also uses its own set of external tools that are described in another section.

Projects List¶

The list of all projects in the SDK can be viewed with the following command:

python3 project.py -p myproject list

Project Structure¶

This is how the structure of a project titled my_project and placed in the ./projects directory in the root of the SDK folder should look:

blend4web/
    projects/
        my_project/
            assets/
                my_project.json
                my_project.bin
            blender/
                my_project.blend
            build/
                my_project.html
                my_project.min.css
                my_project.min.js
            .b4w_project
            my_project.js
            my_project.css
            my_project.html

This app consists of 3 different directories.

1. my_project/assets. Contains media files (textures and sounds, as well as the .bin and .json files) of project’s scenes.
2. my_project/blender. Contains .blend files of project’s scenes.
3. my_project/build. Contains files of the built application.

Project’s main file .b4w_project, as well as the .js, .html and .css files, is placed in the root of the my_project/ folder.

Additionally, the deploy command can create yet another directory, but it’s usually placed outside of the SDK and its name and path depend on directory structure on the target server.

Project Configuration File (.b4w_project)¶

Project configuration file includes all necessary information of your project, including name, metadata, directories, info for application building and deployment.

Project configuration file can be edited manually, but a more convenient way is to use Project Editing interface.

[info]
author = Blend4Web
name = my_project
title = MyProject
icon =

[paths]
assets_dirs = projects/my_project/assets;
blend_dirs = projects/my_project/blender;
blender_exec = blender
build_dir = projects/my_project/build
deploy_dir =

[compile]
apps =
css_ignore =
engine_type = external
ignore =
js_ignore =
optimization = simple
use_physics =

[deploy]
assets_path_dest = assets
assets_path_prefix = assets
ignore =
override =

This is a standard INI configuration file, which includes sections, properties and values.

Creating a Project¶

./project.py init my_project

This command will create a project with the specified name in the current directory. By default the project directory will only contain a config file.

Available parameters:

• -A | --copy-app-templates (optional) create standard app templates in the project directory (my_project_dev.html, my_project.js, my_project.css).
• -C | --author (optional) write an author’s or a company’s name in the config file.
• -o | --optimization (optional) write the script optimization level in the config file.
• -P | --copy-project-script (optional) create a copy of the project.py script in the project directory.
• -S | --copy-scene-templates (optional) create standard scene templates in the directories projects/my_project/assets and projects/my_project/blender (my_project.json/.bin and my_project.blend correspondingly).
• -T | --title (optional) write a title in the config file. Upon building, it will be used inside the <title> HTML element.
• -t | --engine-type (optional) write an engine type in the config file.

Example:

./project.py init -AS -C Blend4Web -o simple -T MyProject -t external my_project

This command will create a directory named my_project, inside which the following files will be placed: my_project.js, my_project.css, my_project_dev.html and .b4w_project.

The .b4w_project file will look like:

[info]
author = Blend4Web
name = my_project
title = MyProject
icon =

[paths]
assets_dirs = projects/my_project/assets;
blend_dirs = projects/my_project/blender;
blender_exec = blender
build_dir = projects/my_project/build
deploy_dir =

[compile]
apps =
css_ignore =
engine_type = external
ignore =
js_ignore =
optimization = simple
use_physics =
use_smaa_textures =
version =

[deploy]
assets_path_dest = assets
assets_path_prefix = assets
ignore =
override =

Developing multiple apps inside a project¶

A project can contain multiple apps. This can be provided by listing the corresponding HTML files in the config file separated with semicolon:

...
[compile]
apps = myapp1;myapp2;
...

If the apps field is empty, every html file in the project directory will be considered an application.

Building Projects¶

python3 project.py -p my_project compile

Builds a project in the projects/my_project/build directory.

Available parameters:

• "-a | --app" (optional) specify an HTML file, relative to which the project app will be built.
• "-c | --css-ignore" (optional) add CSS styles to exceptions in order to not compile them.
• "-j | --js-ignore" (optional) add scripts to exceptions in order to not compile them.
• "-o | --optimization" (optional) specify the optimization level for JavaScript files: whitespace, simple (by default) or advanced.
• "-v | --version" add version to paths of scripts and styles.

Compiler Requirements

• In the root of the directory the single html file must be stored if -a option is disabled
• Scripts and styles can be stored in the app’s root and in the subfolders

Automatic Blend File Export¶

python3 project.py -p my_project reexport

This command will re-export blend files in JSON and HTML formats.

Available parameters:

• "-b | --blender-exec" path to the blender executable.
• "-s | --assets" specify directory with scene assets.

Resource Conversion¶

python3 project.py -p my_project convert_resources

Converts external resources (textures, audio and video files) into alternative formats to ensure cross-browser and cross-platform performance.

Available parameters:

• "-s | --assets" specify directory with scene assets.

Converting of resources is described in detail in the corresponding section.

Deploying Projects¶

python3 project.py -p my_project deploy DIRECTORY

Save a project to an external directory together with all dependencies.

Available parameters:

• "-e | --assets-dest" destination assets directory (“assets” by default).
• "-E | --assets-prefix" assets URL prefix (“assets” by default).
• "-o | --override" remove directory if it exists.
• "-s | --assets" override project’s assets directory(s).
• "-t | --engine-type" override project’s engine type config.

Remove Project¶

python3 project.py -p my_project remove

Removes a project. Removed directories are retrieved from project configuration file.

Upgrading Apps for New SDK Versions¶

While upgrading for new SDK versions often two problems arise:

1. Modules of the new and old versions of the engine do not match.
2. Old and new engine API do not match.

In order to update the list of modules imported in developer version of application go to project source directory apps_dev/my_project and execute module list generator script:

python3 ../../scripts/mod_list.py

For MS Windows users:

python ..\..\scripts\mod_list.py

The console will print the list of modules - copy them and paste into the main HTML file:

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
    <script type="text/javascript" src="../../src/b4w.js"></script>
    <script type="text/javascript" src="../../src/anchors.js"></script>
    <script type="text/javascript" src="../../src/animation.js"></script>
    <script type="text/javascript" src="../../src/assets.js"></script>
    <script type="text/javascript" src="../../src/batch.js"></script>
    <script type="text/javascript" src="../../src/boundings.js"></script>
    <script type="text/javascript" src="../../src/camera.js"></script>
    . . .
</head>

To eliminate API incompatibilities you may require refactoring of your app. All changes are described in release notes.