Talk:Random AV Particle Name Generator

Particle Text Generator v1.0 ~ Help Page

What does it do?

• The Particle Text Generator randomly selects an AV from a crowd & then displays their first name as a stream of particles. For example, if "Joe Smith" is selected, the letters "J", "0" and "E" are emitted as particles out of the prim.
• If no AV's are in the vicinity, the Particle Text Generator will instead emit of stream of text from a selection of your choosing. For example, "HAPPY REZ DAY", "PARTICLE CRUCIBLE", "MY STORE NAME".
• It is possible to turn off the AV selection functionality entirely, and simply use the Particle Text Generator to emit your own text.

How does it do it?

• Once the text has been determined, the Particle Text Generator maps each letter of the text against a font texture UUID. This UUID is then used as the texture for a particle emission. Each letter of the text constitutes a separate particle emission.

• Other attempts to do this are avaliable as free scripts in-world. However these have proven to be unstable and unreliable. This has been blamed on the "lag" but, in fact, there is a fundemental code error in these scripts that causes them to be unstable and unreliable, as well as other ineffcient procedures. These flaws are corrected in the version presented here. See section 'Code Improvements' below for further details.

How Do I Set-up the Particle Text Generator?

1. Simply put the script in a prim and 'Touch'.
2. Select the 'On' option from the blue dialog menu.

How Do I Set My Own Text Mesages?

1. Open up the script.
2. Find the line that says: "list DefaultTextPalette = [".....", ".....", ".....", "....."];". This is the first line of scripting code immediately after the introduction and instructions.
3. Carefully overwrite the existing text with your own text. Ensure you keep within the speech marks.

How Do I Get the Text to Be Seen From Further Away?

As a rule, the larger the prim, the further away that the text stream will be seen. However, draw distance, particle count settings and PC spec also have a bearing. This makes it difficult to predict how each client viewer will render the particle stream.

How Do I Use My Own Set of Fonts?

1. Create for yourself or otherwise procure a set of individual textures for the letters [A - Z] and numbers [0 - 9]. 256 x 256 32bit alpha tga's are ideal. See this superb thread by Chosen Few if you need to learn more about this: http://forums.secondlife.com/showthread.php?t=80851
2. Upload these into SL.
3. Individually right-click each texture and capture it's UUID.
4. In the script, locate the long list of UUID's (variable MasterUUIDPalette). You will see the the letters [A - Z] and numbers [0 - 9] marked on each line. Carefully paste your UUID over the existing one. Do this for each individual character. Ensure you keep within the speech marks for each character.

How Do I Get the Text to Emit in a Different Direction?

With the prim rotation set at 0, 0, 0 the particles will emit vertically. To have them emit in a different plane, simply rotate the prim.

Blue Dialog Menu Options

When the Owner touches the prim, a blue dialog menu is presented. Here is a description of the buttons on the blue dialog menu:

• Toggle power:
  • 'On': Starts the Particle Text Generator.
  • 'Off': Stops the Particle Text Generator.

• Toggle test display mode:
  • 'Defaults': Will only emit text that has been selected from variable DefaultTextPalette. It will not scan the area for nearby AV's.
  • 'Names': Scans the vicinity for AV's. Selects one at random and emits their first name as a particle stream. If no AV's are in the vicintiy, then it will emit text that has been selected from variable DefaultTextPalette until an AV re-enters the area.

• Toggle scan mode:
  • 'X-Axis': Will only scan forward of the local x-axis of the prim. This option is only avaliable in Names mode. (Click on thumbnail 'X-Axis' for diagram)
  • '360degree': Will scan all around the prim. This option is only avaliable in Names mode. (Click on thumbnail '360degree' for diagram)

X-Axis

360degree

• 'SetRange': Allows you to set how far a distance away from the prim that scans for AV's will be performed. This option is only avaliable in Names mode.
• 'ResetScript': Restores all settings.
• 'Help': Links to this page from in-world.

Code Improvements

• This is not the first time attempt use the XYText technology to create a particle text stream. A number of free scripts are available in-world, although they all seem to stem from the same source. For the most part they are unstable and unreliable. This has been blamed on "lag". A text particle stream is indeed a delicate operation and it is particularily susceptible to time dilation and "client-lag" so-called. However, although this is true, the scripts currently in-world also contain a fundamental llParticleSystem() call flaw which, when corrected, helps dampen the effects of time dilation. Additionally, by making other code changes, the effciency of this time-critical operation is significantly improved. A number of comparisons tests between the existing attempts and the one presented here, in both healthy and heavily time-dilated regions, show that the code improvements in this make it into a viable product.

• Client-lag however, is not so easily overcome as it usually a reflection of the PC spec rather than the script as such. High spec PC's, especially those capable of long draw distances and particles set to 8912, will have no problems rendering the characters but tests with lower-end specs have shown that they occasionaly miss letters.

Palette Design

• Take the name "William" (7 characters) as an example.
• In the original scripts, seven 'finds' would required of the 36 entries in the master UUID palette. In a worst case scenerio, this amounts to 252 (7 x 36) individual 'finds'. And this during the time critical period.
• In this new version, before even entering the time critical period and actually firing any particles, we strip the name down to its individual unique characters: "Wilam" (5 characters). We then fetch and use the UUID's for these five characters only. Therefore, during the time critical period, and in the worst case scenerio, only 35 (7 x 5) individual 'finds' are required.
• Although this method adds on a fraction of a second before firing the first particle, the benefit in terms of stability is significant.

Optimisations

This version also introduces a number of code optimisations during the time critcal period. Although performing the same action, the method employed is more efficient. For example:

• string WorkChar = llGetSubString(WorkDisplayText, 0, 0);
• StartParticle(WorkChar);

is changed to

• StartParticle(llGetSubString(WorkChar, 0, 0));

and

• string Texture = llList2Key(MasterUUIDPalette, llSubStringIndex(MasterCharIndex, llToUpper(ParticleChar)));
• llParticleSystem([
• ...
• PSYS_SRC_TEXTURE, Texture,
• ...];

is changed to

• llParticleSystem([
• ...
• PSYS_SRC_TEXTURE, llList2Key(WorkUUIDPalette, llListFindList(WorkCharIndex, (list)ParticleChar)),
• ...];

llParticleSystem() Parsing

In the original versions of the script, parameters such as PSYS_SRC_ACCEL and PSYS_SRC_OMEGA are being parsed even though they have no active effect on the particle emmsion. The new version removes such parameters entirely from the llParticleSystem() call. Furthermore, rather than passing PSYS_SRC_PATTERN and PSYS_PART_FLAGS constants that require interpretating, we directly pass the heximdecimal equivalent.

Burst Rate and System Age

Of all the code improvement discussed, the changes made to PSYS_SRC_BURST_RATE and PSYS_SRC_MAX_AGE are by far the single most significant. In the original Particle XYText scripts (and indeed in many particle scripts circulating in-world) PSYS_SRC_MAX_AGE is erroneously set to 0.00. According to the LSL Wiki, "Zero will give the particle system an infinite duration". So, if you want the particle system to last for one second you set PSYS_SRC_MAX_AGE to "1.00", or "2.00" for two seconds. But, if you set it to "0.00" it will continue pumping out particles at the rate defined in PSYS_SRC_BURST_RATE. However, as the emission of each individual character is controlled by a timer, we do not want a continuous emission, an infinite duration. The absolute maximum duration that we want for the particle system is one character ~ which clearly is the same float value that llSetTimerEvent() has been set to.

Similarly, PSYS_SRC_BURST_RATE ~ "the time interval, in seconds, between bursts of particles being emitted" must not be less than the float value that llSetTimerEvent() has been set to.

It is the combination of these two misunderstandings that has caused previous attempts at Particle XYText to emit, for example, the name "William" as "Wii lll iamm". It is not "lag" causing it but incorrect values for PSYS_SRC_BURST_RATE and PSYS_SRC_MAX_AGE.

The version presented here corrects this by introducing a new variable LetterTimeGap. The float value entered for LetterTimeGap not only controls the timer (llSetTimerEvent(LetterTimeGap)) but is also used to populate PSYS_SRC_BURST_RATE and PSYS_SRC_MAX_AGE. This ensures that only one character is capable of being emitted before the particle system shutsdown. Furthermore, if the region is subject to time dilation, the dilation is passed through to the particle system rather than just effecting the timer. Any time dilation then remains proportional throughout those parts of the script that it effects most.