Creating content for the plug-ins

When creating content for the plug-in, there is not much difference with creating and running content inside Blender or as a stand-alone game. There is one difference however. The plug-in might have dimensions that do not correspond to the settings made in the Blender file. This might create a difference in aspect ratios. The plug-in will match the two as good as possible.

The next figures show the situation of a perfect match. In the 3D view of Figure 2, the outer dotted rectangle shows the area that is to be displayed. The size and shape of this rectangle is set by changing the value in the SizeX and SizeY buttons in the DisplayButtons (F10) of Blender. The size of the plug-in in Figure 3 has been set to the same values.

Figure 2. File in 3D view

Figure 3. Perfect match in the plug-in

Figure 4. Framing of content

In the images in Figure 4, the aspect ratio of the plug-in does not match the Blender file. You'll notice that the plug-in or stand-alone player will try to show the content as big as possible without distortion of the content. The extra areas within the plug-in are drawn in a solid color (red in the figures) that can be either set in the HTML or in the Blender user interface.

How the plug-in or stand-alone player solves the difference in aspect ratio can be controlled in Blender. In the Display Buttons (F10) click on the "Game framing settings" button. You now can select three options: Stretch, Expose or Bars. If you select Bars the extra areas are filled with the color you set with the color sliders.

You can have different settings for different scenes. So you can have a 3D scene with bars and an overlay scene that is stretcht to fit to the output size.

If you select for a single 3D scene the settings as they are shown in Figure 5 you'll get results similar to the pictures in Figure 4.

Figure 5. GUI for Framing in the DisplayButtons (F10)

If you select "Expose", the plug-in or stand alone player will simply show more of the 3D environment. This will usually produce the most natural results but if you have enemies coming from the top or from the sides the user might see them pop up.

Figure 6. Extended framing

And finally, if you select "Stretch", the plug-in or stand-alone player will simply stretch the image horizontally or vertically to fit. This will distort the image somewhat (See Figure 7) but you'll never see bars or more from the 3D world as defined in Blender.

Figure 7. Stretched framing

Jumping to another HTML page

It is possible to have the browser load a new URL from within your Blender file. Send a message with the "To:" field set to "host_application" and the "Subject:" "load_url". The message's "Body:" should contain the full URL you want the browser to load.

Figure 8. Browsing HTML pages from within the Plug-in

Creating a custom loading animation

The file load.blend (download at is an example of a custom loading animation for the Blender 3D Web Plug-in. The selected object has all of the important logic for showing file loading progress. It has a property called "progress". The value of that property drives the Ipo animation curve of the object, causing its size to increase in the Z direction. This is the most convenient way to use the loading information, because it's easy to set up and preview an Ipo animation.

The only tricky part is to get the file loading progress information being sent by the plug-in. The plug-in sends game messages with the subject "progress" as the file loads. Each message has a body which is a floating point value between 0.0 and 1.0 sent as a text string. The value 0.0 means that none of the file is loaded yet. 1.0 means that the file is completely loaded. This information is extracted by the Python script "", which gets all "progress" messages from the message sensor (in case more than one message is received within a single cycle of the game logic). It evaluates the body of the last message, converting it back to a numerical value and assigns the value to the "progress" property of the object.

The camera has some logic attached which causes it to send artificial progress messages for testing the animation. This logic should be deleted from the camera before the file is actually put into use.


  1. The purpose of a loading animation is to occupy the viewer's attention while a larger file is loading. It should be as small as possible so that it loads very quickly. Textures, especially *.tga images, increase file size a lot. Use JPEG images or avoid images completely. Save your file using Blender's file compression tool.

  2. Most of the complexity in this example is for showing the download progress of the larger file. Showing the loading progress is very reassuring to the viewer, but not absolutely necessary. You can use any real-time Blender scene as a loading animation.

Embedding Blender 3D Plug-in in web pages

To embed the Blender 3D Plug-in on your web pages, you will need to add some HTML code to your web pages. Also, you will want to add a link to the Blender 3D Plug-in page ( where users can install the plug-in if it is not already installed on their system. Click-able images that you can use to forward users to the download page are available at the Blender 3D Plug-in page.

The current version (2.28) of the Active X control (the Internet Explorer plug-in) is now able to support multiple plug-ins on a one HTML page. The Netscape version does not support this however. Therefore, you are still advised not to put two plug-ins on a HTML page. This will be fixed in one of our forthcoming releases.

Insert the following HTML tag into your web page and change the parameters to suit your content:

  width = 640
  height = 480

<param name="blenderURL" value="">
<param name="loadingURL" value="">
<param name="ForeColor" value=65280>
<param name="BackColor" value=255>
<param name="useFileBackColor" value=1>
<param name="frameRate" value=20>


This code works for both the ActiveX control and the Netscape plug-ins.

The part between the <object> and the <EMBED> tags relates to the ActiveX control.

The <object> tag is followed by a list of parameters:

The Netscape plug-in settings can be found between the <EMBED> and </EMBED> tags. Most of the parameters are the same as those of the ActiveX control.

Parameters that differ are:

Color values should be passed to the ActiveX control in a format known as OLE_COLOR. The red, green and blue components of the color are stored in a single value. To determine a BGR value, specify blue, green and red (each of which has a value from 0 - 255) in the following formula: BGR value = (blue * 65536) + (green * 256) + red

Some parameters of the plug-ins can be dynamically accessed (through Javascript for example). This means that you can interact with the plug-in from your HTML code. For instance, you can change the URL of the Blender file from the HTML page with a button by adding the following to your HTML page:

<input type="button" 
value="load other production" 

This feature is currently not available for the Netscape plug-ins. We are planning to add Javascript capabilities in the next release.

Another very powerful option is to send messages to the Blender file running inside the plug-in. This way you can change the behaviour of your production from the HTML. The following form allows you to type in messages in the HTML and send them to the plug-in:

<form onSubmit="Blender3DPlugin.SendMessage(
	    the_body.value); return false;">


<td><input type="text" name="the_to" value="" size=30></td></tr>

<td><input type="text" name="the_from" value="" size=30></td></tr>

<td><input type="text" name="the_subject" value="" size=30></td></tr>

<td><input type="text" name="the_body" value="" size=30></td></tr>

<input type="button" value="send"
	    the_from.value, the_subject.value, the_body.value);">