Guild of Writers

Revision as of 13:33, 19 May 2008

The new plugin release significantly changes many of the Age building conventions and properties used in older versions to the point that older Ages exported with the new plugin may simply fail to operate properly.

I will list the changes most likely to break existing Ages, and detail how to update them for use with the new plugin.

Drawable (Graphics) Changes

• The plugin now reads the "Map Input" settings. This means that the texture coordinates applied to the mesh will be the same as the ones that would be applied by the Blender raytracer. In order to make your uv mapped materials compatible, you must set the UV button for each texture layer of your material that uses a uvmapped image texture. (the only exception is environment maps)

• The plugin now automatically assigns all lights in a scene to each object in the scene, meaning that all your objects will be dynamically lit by plasma. In order to stop all lights from affecting an object you must set the "Shadeless" button in the material panel of the material settings. If you had very specific light settings before, and want to preserve them, you can use lightgroups. First, select the lights you want to affect your object, and press ctrl-g to add them to a group. You can change the group name in the objects panel (F7) under "objects and links". Now select the object you want to be affected by this group and enter the name of the group in the GR: field in the shaders panel under Shading Tools (F9).

• The plugin now reads the specular color of the material. This defaults to white on new Blender materials, meaning your objects will probably appear excessively shiny if they are dynamically lit. You can change the specular color by selecting "Spe" and changing the color sliders.

• It is also worth noting that the plugin has always read the "Amb" slider in the "shaders" panel of the material settings. If you are using vertex colors, this should be set to 1. (it defaults to .5)

• The plugin now reads the "TwoSide" button in the UV edit mode settings. You can now make your materials double sided.

• You can now assign multiple materials to a single object mesh. To do this you must use the Material controls in the "link and materials" panel of the mesh options. (new, select, assign, delete, deselect) "1 Mat 1" refers to the number of materials on the mesh, where the currently active material is 1 out of a total of 1 materials.

While this is not entirely neccesary to use this to update existing Ages, it may be useful in case you already had multi-materials and suddenly have strange results in plasma because of it. In order to correctly assign multiple materials to a mesh:

First, in UV mode, apply textures to all the faces you want. This will be your UV mapping. (you can use multiple textures here by selecting individual faces before changing the uv image) Once you've got that done, and everything looks dandy in the textured view, go to the materials settings for the object. Set the texture in the material to one of the textures you used while uv mapping. Set map input to UV. Now go to the Editing tools (F9) and hit "new" under 1 Mat 1. It will change to 2 Mat 2. Go back to the materials controls (F5) and look at the texture in your material. Click the number 2 to the right of the texture name in the texture view, and click "single user" in the popup. This will unlink the texture so that you aren't changing your old material's texture too. Now set the material texture image to the second texture you used. Now go back to the Editing tools (F9) and take your object into edit mode. (tab) Select the faces that you want to have this second material assigned to. Now click "Assign". Now those faces will use the second material. If you want to assign the first material to some faces, click the arrow next to 2 Mat 2 to change it to 2 Mat 1. Now clicking assign will assign the first material to the selected faces in edit mode. You can repeat this process (new mat, unlink texture, change texture, assign faces) to add as many materials as you want to the same mesh. You can check your materials by doing a Render, as the material settings are used by the raytracer.

Collision (Physics) Changes

• All objects now use the "Bounds" options in the logic settings to set collision, rather than the col_type property. The conversion wizard will not write this property, so you will have to set it manually. The types available are:

1. Box (equivalent of col_type 1)
2. Sphere (equivalent of col_type 2)
3. Cylinder
4. Cone
5. Convex Hull PolyType (equivalent of col_type 3)
6. Static TriangleMesh (equivalent of col_type 4)

Static TriangleMesh is the equivalent of col_type 4. To help in resetting your collision properties, a wizard has been added to mass set the Static TriangleMesh bounds option. Scripts > Wizards > PyPRP Wizards > Assign Default Bounds to Selected Objects will set the bound type for all of the currently selected objects.

Region (Logic) Changes

• AlcScript is implemented and used extensively for nearly all simple logic actions.
• Footstep regions now use the "surface" string property to set the sound rather than the "footstepsound" integer property. The surface strings and their equivalent integer values can be found here.

• Camera regions now require an AlcScript to function. An example script:

<camera region name>:
	region:
		type: camera
		camera:
			messages:
			  - newcam: <camera object name>
			
<camera object name>:
	camera:
		brain:
			type: <Camera type (fixed, circle, avatar)>
			xpanlimit: 0.8 (amount the user can pan the camera with right mouse button)
			zpanlimit: 0.8 (values range from 0 to 1)
			poa: 0,0,6 (This is the Point on Avatar)
			offset: 0,6,6 (For avatar cameras only, location relative to avatar feet)
			flags:
			  - followlocalavatar
			  - maintainLOS
			circleflags: (only neccesary for circle cameras)
			  - farthest

• Climbing regions now require an AlcScript to function, and the "easy" climbable regions are not recognized. Follow the tutorial here to learn more about new ladders.

<name of top ladder region>:
	type: region
	region:
		type: ladder
		ladder:
			direction: down
			style: twofeet
			loops: <climbing height, as calculated>

<name of bottom ladder region>:
	type: region
	region:
		type: ladder
		ladder:
			direction: up
			style: twofeet
			loops: <climbing height, as calculated>

Ladder regions must also have the Blender text properties:

string type region
string regiontype climbing

Conversion Wizards

You can also try the automatic conversion wizards to upgrade your age to use the latest plugin.

The goal of the converters is to keep your age looking and behaving the same as it did with the old exporter, so that there are no surprises.

NOTES: 
1. These converters are a work in progress.  This means that 
there will be some items that do not look or behave the same after 
exporting with the new plugin.  We appreciate your patience and your
help in tracking down these discrepencies.
2. This converter is only for ages that currently work with the 
stable v0.5 plugin.  If you have an age that was created with v1.0 
or later, do not use this wizard.

To use the converters:

1. Your age must export correctly with the stable v0.5 plugin before using this converter.
2. Copy your blend file to a new file, i.e. MyAge_convert.blend. Please keep your original blend file safe somewhere until the new plugin is more robust.
3. Start Blender and load your new copied blend file
4. Change one of your Blender windows into a Script Window
5. From the Scripts menu, choose Wizards -> PyPRP Wizards, then choose Upgrade Book. A popup dialog will appear, with a toggle button that says "Delete old book". This will delete the book objects after converting them to AlcScripts. Since you have your original blend file backed up, leave this option selected and click OK. After it completes, it will tell you that it upgraded the books and deleted the objects.
6. From the Scripts menu, choose Wizards -> PyPRP Wizards, then choose "Add missing Blender materials and textures". This will look for any mesh with faces that have UV coordinates assigned and will create a material if it does not have one, and will create a texture. It will also change any ORCO map input to UV, set specular to black (otherwise all lit items will be shiny), and will delete any null materials you may have. (Null materials will cause the new plugin to throw an exception, since it now handles multiple materials.) After it finishes, it will report the number of materials and textures created.
7. From the Scripts menu, choose Wizards -> PyPRP Wizards, then choose "Upgrade properties". This will convert all objects that formerly used properties but now use Blender GUI controls or AlcScripts: collision, kickables, ladder regions, lights, cameras, camera regions, footstep sounds, swimming detectors/surfaces, clickable objects and click regions. At the end it will report how many objects and properties were converted.
8. Save your blend file. Then export your age.

If you encounter any issues with the converters, post your issues on the forum topic here.