FAQ / Common pitfalls

This is a list of known problems, (hopefully) useful hints and solutions for confused users:

1. How do I use this program?
2. The program works, but the more I use it the longer the files get.
3. Nothing happens after clicking on the program's icon.
4. My command files no longer work after switching to version 4
5. How do I make transparent car windows?
6. How do I create instances with rvglue?
7. What happened to tedelete and tecolor?
8. I got some error with 'PANIC'. What should I do?
9. Some of my instances aren't solid anymore after using rvglue
10. rvglue complains about missing instances, but they are there!
11. rvglue complains about missing instances, but I didn't use them!
12. I'm confused about the program. How does it work?
13. I don't want to write the same options over and over again!
14. What is the src directory for? Do I need it?
15. Why is the package named "rvtmod5.zip", and not "rvglue.zip"?
16. How do I create an empty track body?
17. I have a website. May I distribute rvglue?
18. Why can't this program be a real windows program?
19. What do all those terms like mesh, polygon, vertex and edge point mean?
20. rvglue ignores the options for an instance!
21. rvglue refuses to run and tells me I attempted to "read and write the same file". So what?
22. rvglue warns me that that my ".fin may cause unexpected results". What???
23. rvglue creates invisible obstacles!

1. How do I use this program?

This is a question that cannot be answered. There is lots of documentation among these pages, read it. All. Especially read the Quick'N'Easy Tutorial. If you have problems, ask. Tell the people what you wanted to do, how you tried to do it, what went wrong and how you noticed something went wrong.

Include at least everything you wrote in the command file in your question. Try to write in a language everybody understands. If you ask

hi ppl, i wanted 2 use it but error there. can u help e on this prob if pop ack nop?

Hi. I wrote a command file which looks like follows:
(...)
I've runned rvglue on it, which gave no error messages. The .w and .ncp files were created, and have correct names. But when I try to play the track, I'm stuck to the ground. Everything seems solid and looks right, but my car isn't able to jump.

2. The program works, but the more I use it the longer the files get.

You are probably reading and writing the same file. If your command file looks like

  create( nhood1 )
  nhood1.w

3. Nothing happens after clicking on the program's icon.

This is no windows program. It opens no windows. It does not ask you what it should do. You have to write some files on your own in order to use the program.

Read the Quick'N'Easy Tutorial.

4. My command files no longer work after switching to version 4

Some things changed in version 4 and require some modifications on your version3 command file:

• The tedelete and tecolor options are gone. Read Question 7.
• Colors are now specified as decimal numbers, as some people had problems using hex triplets. Read the description of color definitions.

5. How do I make transparent car windows?

It is a bit tricky to do this, so here is a step-by-step guide:

Let's assume your car body is already exported and you have it's file somewhere, named "mybody.m".

1. Get "rvtexmap" and Chaos' tool "rv-sizer". Both should be available at RHQ and RVEX .
2. Make an instance out of your car: Rename the file to mybody.prm.
3. Enlarge it. A car is just too small to place track zone in it, so we'll work on a larger version. This is done by rv-sizer. A factor of 50 gives a good size:

   rv-sizer mybody.prm sa=50

4. Choose a track that contains no instances at all - like a freshly exported lego track. If you are not sure, just delete (or rename) the .fin and .fi- file. Copy the instance into the track's directory.
5. We need an empty track zone file. Delete (or rename) the .taz and .ta- file.
6. Go into instance editing mode, and insert your car instance in a arbitrary place. Do not rotate the car at all.
7. If the car looks weird (invisible at all, or some polygons are missing), let rvtexmap fix the file:

   rvtexmap mybody.prm *:*:*=a:*:*

   The textures are now taken from the track's a.bmp file, but that doesn't matter as long as you can see the car.
8. Go into track-zone editing mode. Place one or more track zones, all with ID 0, so that:
   • Every edge point of every car-glass polygon is inside a track zone.
   • Every polygon that doesn't belong to the car's window has at least one edge point outside all track zones.
9. Write a command file that lets rvglue make the windows transparent. Example (assuming your car instance is "mybody.prm", the created .fin file is "bongo.fin", the .taz file is "bongo.taz" and you want the windows to be 50% transparent. The red parts indicate where you have to change something if these assumptions are wrong):

   create tbody.prm bongo.fin ( default ( off ) mybody ( tazsplit ( bongo.taz 0 ( transparency 128 ) ) ) )

10. Run rvglue on it.
11. Now proceed with the created instance. (tbody.prm in our example)
12. Resize it to it's original size:

    rv-sizer tbody.prm sa=0.02

13. Make a .m out of it. (By simply renaming the file)
14. Done.

6. How do I create instances with rvglue?

Write the desired suffix into your create statement, like "create myinst.prm". The program will then create the files myinst.prm, myinst.i-p and myinst.ncp.

That way you can do anything you used to do with tracks. Even a conversion from track bodies to instances is possible. But keep in mind that instances cannot hold as much data as tracks, and thus such a conversion will fail if you don't cut off much of the track.

7. What happened to tedelete and tecolor?

Both options disappeared in version 4. The new legosplit option provides a more flexible way to access parts of lego tracks.

The description of tedelete and tecolor give some hints on how to use it.

8. I got some error with 'PANIC'. What should I do?

Look whether a new version of rvglue is available at ali's page (external) . If not, follow the instruction on screen.

'PANIC' messages appear when rvglue detects that something got screwed up by earlier calculations. (Like it wants to rotate an instance but the instance wasn't even loaded by the instance loading parts.) This is always a program bug, and the program panics because it cannot even rely on itself.

9. Some of my instances aren't solid anymore after using rvglue

Instances that are far away from the track's body are never solid. If you started with a lego track, placed instances in it, and then cut out some part of the lego, your instances may become off-track. The solution is to place dummy instances and to glue them into the body to enlarge its dimension, and finally to glue all those off-track instances into the body.

To explain it a bit more detailed. Consider this situation:

View from top:

The blue thing is the track body (created by rvglue, or exported from the lego editor). The green and red things are instances. The green one has no problems - it's inside the bodies range and can be solid. The red one is "off-track": It cannot be solid at all.

Now the solution is to enlarge the body so that the red instance is inside it's range. We can do this by gluing a "dummy" instance into the body:

View from top:

Now the red instance is within range, and can be solid.

As this limitation comes from the track's .ncp file, the dummy instance needs only to be present there, and you can safely make it invisible. And if you plan to glue the red instance into the body in later steps, you don't need the dummy instance then anymore. The problem affects only instances.

10. rvglue complains about missing instances, but they are there!

If you get error messages about instances with shortened file names (rvglue complains about myinstan.prm, although you used myinstance.prm), then you have to give rvglue a hint about the real name with the realname option, like in

myfin.fin (
  myinstan ( realname myinstance )
)

This problem occurs when instances have names longer than eight characters, and sometimes even shorter names. Re-Volt always writes only the first 8 characters of instance names into the .fin files, and sometimes shortens the names even further.

11. rvglue complains about missing instances, but I didn't use them!

It may be that you used that instance earlier, and deleted the .prm file. Then Re-Volt will completely ignore that instance, although it is still referenced in the .fin file.

Use an arbitrary dummy instance in that case (take any instance and rename it to the name of what rvglue misses) and cur it out using the off option:

myfin.fin (
  dummyinstance ( off )
)

12. I'm confused about the program. How does it work?

Most problems can be answered if you understand how the program works.

The program relies on your command file, and everything it does has some direct representation in you command file.

Basically, the program reads some input files, applies some modifiers on the input data, and writes some new files that contain the result of the modifiers:

Different input files can have their own set of modifiers:

Some modifiers (options) split up the incoming data and feed them into other modifiers (like legosplit):

For an example: This command file ripoff looks weird:

create yeppa

user001.w (
    legosplit (
        lamp  ( off )
        track (
            tazsplit (
                some.taz
                0 ( surface mud )
                1 ( transparency 128 )
            )
      )
      pwall ( color 255 255 255 )
    )
)

It can easily be understood, if you know how the data passes through the program:

13. I don't want to write the same options over and over again!

Look at this command file:

create ( nhood1 )

haus01.fin (
dachkies ( s(15) )
dachkikl ( s(15) )
)
haus02.fin (
dachkies ( s(15) )
dachkikl ( s(15) )
wassramp ( s(21) )
)
haus03.fin (
)
haus04.fin (
dachkies ( s(15) )
dachkikl ( s(15) )
boxkdach ( s(3) )
dachbeto ( s(3) )
luftscha ( s(21) )
wassramp ( s(21) )
)
haus05.fin (
)
haus06.fin (
teppichg ( s(6) )
teppichk ( s(6) )
)
haus07.fin (
dachkies ( s(15) )
dachkikl ( s(15) )
luftscha ( s(21) )
)
haus08.fin (
dachblec ( s(3) )
glas ( s(3) )
)
haus09.fin (
dachkies ( s(15) )         
dachkikl ( s(15) )
bumpkies ( s(15) )
)
drumrum.fin (
)

It's ugly to read, and contains most commands multiple times. Why not shortening it? This file does the same, and is much better to read. Only by using global:

create nhood1

global (
  dachkies ( s(15) )            
  dachkikl ( s(15) )
  wassramp ( s(21) )
  boxkdach ( s(3)  )
  dachbeto ( s(3)  )
  luftscha ( s(21) )
  teppichg ( s(6)  )
  teppichk ( s(6)  )
  bumpkies ( s(15) )
  dachblec ( s(3) )
  glas     ( s(3) )
)

haus01.fin
haus02.fin
haus03.fin
haus04.fin
haus05.fin
haus06.fin
haus07.fin
haus08.fin
haus09.fin
drumrum.fin

Now, we can make it even better by using define. It is a bit longer now, but easier to read and maintain:

create nhood1

define (
  bump    ( surface bump )
  slip    ( surface slippery )
  greytr  ( surface 3 )
  lighttr ( surface 6 )
)

global (
  dachkies ( bump    )            
  dachkikl ( bump    )
  bumpkies ( bump    )
  wassramp ( slip    )
  luftscha ( slip    )
  boxkdach ( greytr  )
  dachbeto ( greytr  )
  dachblec ( greytr  )
  glas     ( greytr  )
  teppichg ( lighttr )
  teppichk ( lighttr )
)

haus01.fin
haus02.fin
haus03.fin
haus04.fin
haus05.fin
haus06.fin
haus07.fin
haus08.fin
haus09.fin
drumrum.fin

14. What is the src directory for? Do I need it?

The directory called src contains the program's source code. You may find it useful if you want to know how the program works, how I did some calculations, want to recompile the program with a different compiler, or want to add features to the program.

If this doesn't apply to you - or you can't program in C++ - you can safely delete the whole directory as it is completely useless for you.

15. Why is the package named "rvtmod5.zip", and not "rvglue.zip"?

Well, in the beginning I planned to include a second program in the package, and thus chose such a name for the package. Later it became obvious that that second program was impossible, and I dropped the idea.

On the other hand, nobody ever complained about that, and so I decided to keep the name.

Now, with release 4, there are multiple programs in the package, and so the distinction between package and program finally made sense.

16. How do I create an empty track body?

I've seen lots of people doing something like:

create( empty ) USER_xyz.w ( tedelete ( pwall rwall carimg floor lamp box track ) )

Other people asked for a special delete-all keyword (like 'tedelete( all )').

Such a command file instructs rvglue to read the file USER_xyz.w, split it up into several parts, then delete every part, and write the rest to empty.w.

Actually, there is obviously no need to read anything. If you want an empty body, you want rvglue to read nothing and write it out. So, the correct way would simply be:

create( empty )

But there is another problem: You can't do anything with an empty track body! An empty .w file may be useful (and can be created as shown above), but an empty .ncp file for your track is devastating. Due to some re-volt internal limitations nothing in your track can be solid if the .ncp is empty. This means: Instances that have their own .ncp files will be un-solid, too. So, empty .ncp file are not what you want to have. (see also Question 9)

Furthermore, empty .ncp files written by rvglue are corrupt. It's a rvglue-bug. But as empty .ncp files are waste in either case, this bug won't be fixed.

17. I have a website. May I distribute rvglue?

You may. Just redistributing the zip archive as it is for free is always fine.

Read the license agreement for this package, the GPL. Don't fear reading it, it is not as long as the other licenses you read before, and it should be nice to read something that gives you as much rights as possible in contrast to all the rights taking licenses.

18. Why can't this program be a real windows program?

First, because I don't want it to be one. I am using this program under Linux, which is only possible without the windows stuff.

Second, because writing user interface takes lots of time. Time that I can't spend on adding cool new options.

Third, because I can't even imagine a user interface that is as flexible as the command files.

19. What do all those terms like mesh, polygon, vertex and edge point mean?

Lets just look at an example, a simplified house:

This house is made of flat triangles and "quads" (four-edged flat things). To visualize these flat things we'll just move them a bit apart:

Now we can clearly see what makes up the house:

• The flat things are called polygons. They come in two flavors: triangles and quads For 3D-Studio users: They are mostly equivalent to "faces".
• Polygons are defined by three or four edge points (the yellow balls). Those points are called vertices.
• For better handling (inside the 3d engine) some polygons are grouped to meshes. (Like the house)
• A Re-Volt instance consists always of exactly one mesh, while track bodies (.w files) contain multiple meshes (Several thousands of them for a lego track).
• In Re-Volt there can't be any polygon that doesn't belong to a mesh. But often there are meshes that consist of one (or even zero) polygons.

If you want to see the polygons that make up an instance, you can use the program "rvmark" from the rvminis collection.

20. rvglue ignores the options for an instance!

Check whether you wrote the suffix ".prm" into your command file. The instance option list begins with an instance's base name without ".prm".

21. rvglue refuses to run and tells me I attempted to "read and write the same file".

The most common mistake people made with glue3 was that they had the idea "I merge this .fin file to my .w" and wrote a command file like this:

create track

track.w ( something )

The next thing they noticed that framerate began to suffer, some options did work, some other not, surface properties were random, and lots of other stuff.

The problem is that if you read and write the same file, the work rvglue does is based on prior runs of it. If you merge something into the file, it will be added on every run of rvglue. So, after ten runs, you have the added things ten times in the resulting track, at the same position.

Always use different files for input and output.

22. rvglue warns me that that my ".fin may cause unexpected results".

If you want to create a track based on instances, or want to merge the instances to the track body, do not do this:

create track

track.fin ( something )

It will seem to work, but if you run re-volt, the instances will be there two times: One time loaded from the track body, and a second time loaded from the .fin. That would lead to funny results.

If you put your instances into the track body, the instances are no longer needed. So, remove the .fin file. (Or rename it). If you do so, make sure to delete the ".fi-" file, which is a backup of the .fin, to prevent re-volt from restoring the .fin.

23. rvglue creates invisible obstacles!

Sometimes - mainly when doing something with lego tracks - the thing rvglue created contains something invisible that is like a invisible barrier. In 99% of all cases it is caused by lego walls that are hidden under the track surface:

To get rid of it, do one of the following:

• Delete all lego walls (with legosplit and off).
• Delete just the problematic walls (with tazsplit and off). Create a special track zone file for it, and for every such wall, insert a small zone that covers the wall only. The complex example and it's demo track shows how to do it.
• Lower collision data for the problematic polygons (with lower_coll).