Attraction! - documentation

Attraction! v2 - a fratricide product

Welcome to the world of Attraction!
Be prepared to spend some entertaining hours with this gimmick.

blah

go to the download section to download Attraction!

Overview

This document has the following sections:

What is Attraction?
Why did fratricide develop such a product?
Download
Installation
Quickstart
The Template Generation Window
What the values mean
The Controller Window
The Physics
The Display
Hints
Bugs
Information for developers
About fratricide
Feedback

What is Attraction?

Attraction! is a freeware particle system simulation that attempts to be entertaining. This is why we call it a Gimmick.

It enables the user to define different types of particles and put them in the system to see how they behave and interact. To know this, rather than see it, take a look at the Physics section. fratricide has numerous ideas on how to evolve Attraction. In case feedback is positive, we will continue to work on Attraction and make it what you want it to be. Take a look at the feedback section to learn how to steer us.

Why did fratricide develop such a product?

Simple: It promised to be the most fun to do such a gimmick application. As you might have noticed we are trying to coin this term - a Gimmick - because we think a happy OS is a good OS, so add some color. We'd like to encourage all developers to do a Gimmick alongside their serious work - its a welcome distraction and also much fun. Also skills one in timing and ui-design since a gimmick should be realtime and easy to use. (Don't know wether our one meets the criteria) Please consider supporting the term Gimmick with your own entertaining application.

Download

Attraction v.2 for BeOs Preview Release is available from

the Be ftp site

this location.

Attraction v.2 for BeOs Advanced Access Preview Release is available from

the Be ftp site

this location.

mail me with any problems.

Installation

If you haven't already, use unzip to extract the file Attraction_200_PR.zip. If you dont have it, you should get unzip, which is available for download at ftp.be.com/pub/contrib/utilities/ or from BeWare. Zip does a better job at preserving file attributes than the gzip/tar couple.
A folder called Attraction! will be created with the Attraction executable in it. Click it! To review the html, you can just click the help button in the Controller Window. (I hope the html--file has the correct type, otherwise you should get typesetter, set the correct type, and tell me).

Quickstart

Start Attraction! by double-clicking its icon. Ignore all windows except the Attraction! - display window for now and start clicking and moving the mouse around in the window. You should see particles pop up and integrate into the system. The number of particles is being limited in order to stay realtime. Note: the window is rezisable, dont make it too big, though. Explore the other two windows on your own or read the sections The Controller Window and The Template Generation Window.

The Template Generation Window

The particle template manager contains a list of particle templates. To use a template, select it. The values will be copied into the below particle generation template form and sent to the model thread to be used when the mouse is clicked in the display window.

Try changing the values to figure out what each one means. Dont forget to invoke the control you just changed to apply the changes. In case you want to revert to the old version of the template you have to select another one temporarily and then reselect it. The values will only be stored to the list by clicking the store button. Having fiddled around with the values for long enough, you might want to store the template under a different name: Just enter the name in the name field and click the store button. The new template will be added to the bottom of the list. Updating a template will also move it to the bottom of the list, so most recently changed template are always at the bottom. All the new button does is set the name to untitled. You can also just enter the new name directly. The template will be created when you click the store button.

What the values mean:

friction

A particles speed will be multiplied by its friction value each step. This means a value of 0 makes the particle unmovable (not entirely, as I encoutered. if it should move, it's a certain sign that floating point precision is exceeded)
A value of 1 means a friction-free particle: it wont stop by itself.
Typical values are: 0, 0.5, 0.95, 0.999, 1.

mass

The particles mass will be used by other particles to determine how strong the influence is.
The other effect of mass is that the particle becomes more hard to move, because the velocity vector is multiplied by it before being added to the speed vector.
Be careful with high masses, they might easily blow the system into pieces you'll never find again.

size

Determines the displayed size of a particle. You shouldn't use more than 25. Smaller sizes greatly reduce the time it takes to draw them. A size 2 particle should draw about 25 times faster than a size 10 particle (overhead not considered).
You can use sizes like 2.3 or 3.8. A 3.1-particle will look (probaly inconcievably) bigger than a 3.0-particle.

Use the special value of 0.0 to draw the particle as a pixel (it looks much worse than 1.0, but its much faster, too). Use 0.0 if you intend to create many particles of that type.

color

You can guess that. Special value is color 0,0,0 (black, upper left in the color selector). It will use the colorcycle mode from version 1.0.

position, speed

Determines the position and speed the particle will initially have. The display region is (0.0,0.0)-(1.0,1.0). You will usually check the mouse check-box for position. Checking moused-speed and not moused pos will create the particle at the given position and use the relative mouse-position as initial speed-vector. Using the mouse for both position and speed will result in the following creation behaviour: Clicking the mouse will determine the position of the new particle. Hold the button down and move the mouse to a different position to set the speed vector and create the particle.

Particle creation rate considerations.

You can at max create one particle a frame. The particles will only be created if the one created last has a certain minimum distance from the mouse position. So clicking in one point of a fresh system and holding the button will only create one particle. Move the mouse to create more or wait for the particle to move somewhere else.
This mechanism avoids particles to be real close to one another or even at the same point. This would result in massive velocity applied and the particle moving way too far a distance per frame.

relation to others

Each particle relates to all others the following way. It tries to keep the desired distance plus the partners desired distance. If the distance of the two is not the desired distance, a force will be applied to change that state. The forces that result out of all the relations are added up and later applied to the speed vector. Use the Attraction strength field as a general force multiplier to limit or enhance the effect.
Typical values for the strength are: 0.005, 0.00001, 0.01.
Typical values for the desired distance are: 0, 0.01, 0.1
You can also use negative values for the distance to attract particles that usually try to keep a distance even below that distance.

The Controller Window

The controller window offers various controls to control the system in general as opposed to controlling single particles using particle templates.

model control

(out of order) the respect bounds checkbox determines wether or not the particles bounce off the windows frame.
you might want to pause the calculation thread for two reasons: you have a caclulated sequence you want to keep viewing in loop mode or you want to create e.g. four particles in the edges at the same time. Note: In paused mode particles will still be created, just not displayed. the delete particles to stay realtime checkbox is disabled in loop mode (see tape control). I know the mechanism deletes more particles than really necessary and also does this in a very unsmooth way. On the other hand, if you keep holding the mouse button it will even drop frames. I tried to find something in between and failed to make it work dynamically as untill now.
You can protect the first n particles you created by entering n into the protect first n particles text control. dont forget to invoke it by pressing tab or enter. if you cant enter values, make sure the loop checker is unchecked and the controller has focus (click its border or title bar). (i know this is not nice)

tape control

The tape is a buffer to record the calculated frames (as position/size/color data) in. You can see the tape's length in the line above the blue status bar. As frames are calculated, they are added to the tape at the end and the size will be increased. To save your system from crashing when the swap space is full, you should limit the tape size to some reasonable value (maximum tape size control). These values are given in seconds.
Note: The controller window will accept first clicks. If you want to enter values, you have to first activate the window by clicking its title-bar or its border. Sorry for that inconvenience, but I like being able to click the reset and rewind buttons without loosing focus on the template window.
Ah, the buttons: reset will delete all particles and empty the tape.
The rewind button will rewind the tape to its beginning. You will frequently use this to review the calculated sequence at nicer speed, when the calculation is not realtime anymore. The fast forward button will position the tape right before its end, so you can see particles you create. The blue bar will show this position relative to the tape length. The loop checkbox will automatically rewind if calculation is too slow. (note: checking it will uncheck and disable the delete particles to stay realtime checkbox out of obvious reasons). Check it to lean back and observe a slowly calculating system.

display control

The framerate bar shows the current framerate (averaged over the last 16 samples taken). It will change it's color according to wether it meets the desired rate or not. again, to enter the desired rate, you'll have to focus the controller window by clicking its title or border.

The rendermodes

are explained in the display section. just check them out.

programmers optimization info

This is for developers that want to now how long what takes. Shows how many particles are in the system and how long it takes to calculate, record to tape, draw to bitmap and blit to the screen one frame. the sum*rate value is all these timings added up and multiplied by the framerate. a value of 2.0 means that both processors are optimally used. If you should encounter this value, there's something wrong :)
All these values are averaged over the last 16 samples.

The Physics

Keep in mind that it"s a stepped simulation, so actually cant be associated with the word Physics.
Each particle has a position and a speed attribute. That should be self-explanatory so far. Both are 2 dimensinal vectors (double precision floating point). At each step each particles speed vector is added to its position vector. We have a moving particle. Further I introduced a particle attribute called velocity (dunno about the term, I'm a german guy) used to sum up the forces that influence the particle. We apply the velocity to the speed the same way we applied the speed to position for each particle at each step. We have a particle that isn't isolated, but influencable.

So what do we add to the velocity? Let's be a particle for a second and look around: other particle. ok, then we take each one after the other and take a look at the distance. We add the distance vector time a factor to our velocity accumulator: The other particle forces us to move some way. Now whats the factor do? It calculates by multiplying the 'attraction' attribute with our current partners mass and the (scalar) distance between the distance and the desired distance and dividing by the distance, the desired distance being mine plus the other particles one. Let's be a processor and do this 10,000 times (for 100 particles) a frame. At 25 fps we get about 4 microseconds to do it. So, guess let's not be a processor for a second. We've got a system of moving particles that try to keep a certain distance to each other all at the same time. If the particles also had the will to go as fast as they could, we'd look at a phenomenon called traffic.

The Display

I'll start with the blind mans mode: it chooses a rectangle around the particles position and just fills it with the appropriate color.
In the other two modes the rectangle is taken as the render-area. for each pixel the distance to the position is calculated, squared and used as alpha-value. this allows sub-pixel positioning (like the beos font-routines). In 32 bit, the particle could theoretically be perceived to move 1/256th pixel.

32 bit would be nice, but up to this point I saw no need, because my aged 66mhz bebox would fail to push all that data through the double buffer.

Hints

To be able to enter values in the Controller Window you will have to first activate it, cause it accepts first clicks.

Size zero means only one pixel (for fast display)

For advanced thinkers: check out negative values.

Bugs

There's no bucks in this. Oh, bugs, there's one that seldomly shows up. It's a data access exception in the draw thread.

I removed a division by zero-check in the heart of the algorithm shortly before release - probably not a good idea...

I put it back in cause it seemed slower.

Information for developers

I'm will share (parts of) code or give hints and help. I'm also eager to receive hints and help and suggestions.

Please write a gimmick!

About fratricide

fratricide is something that hasn't incorporated its form yet. it's the "in-between and all around" of two persons, their ideas, their visions. visit our homepage

Feedback

Please let us know how you like this. Send any comments/suggestions/flames/... to NFischer@studbox.uni-stuttgart.de or use the following form. You can also do both.

Please take the time, you will make a difference! Thanks for helping us.

If this is not your networking computer, you can also find this form at: www.w-4.de/~dfischer/fratricide. In that case: special thanks for reminding yourself :)

Of course we will not give your email-adresses to anybody else.

We're thinking about giving future shareware releases to people that took part in this survey for free and are aware of thus influencing the survey results :-)

The Attraction Survey

Name:
eMail:
I want the next free release by email
I want the results of this survey by email
I also know the old Attraction v1.0

How do you like Attraction?

it sucks
its no good
I always choose the middle button
its cool
great

What would you consider to be a reasonable price for Attraction?

I would'nt even download it!
I'd at least take the time do download it
ten cents
a quarter
up to a dollar
up to five dollars
more

I would like to see the following features in the next release (note that checking more features decreases strength of each) Also be aware that some features are exclusive - a decision has to be made - this is why we're asking, we'd implement all of the features if it was possible :)

the Particles shouldn't be in a window, but right on the screen, with the desktop as background.
the user interface has got to get easier/better/more compact/...
Think about how you could make the gui more zappy.
I want the version 1.0 alerts back!
make the section boxes minimizable to only the title.
I'd like to be able to select particles and perform modification actions on them
It'd be cool to grab particles and drag them around.
The Particles should have context-menus.
It should be possible to limit the relation range of a particle to only include certain other particles
Make it possible to use any bitmap for particles instead of the rendered blobb.
The particles should have a face and talk to me.
I want to be able to do more particles in realtime
It'd be cool to be able to save a calculated sequence to disk
It'd be cool to be able to save a sequence as particle creation information (smaller files than above)
I want to be able to save and load template files using any name, not the fixed Attraction.template file
Do a correct installer.
You should think about adding sound i/o.
Create more fancy display options like motion blurring and fading trails
You should inplement a bitmap-level "tape"
ZOOM! GRID!
The particles should live on a moulded editable surface seen from above.
3D
Use 32 bits for display instead of 8 (much nicer quality, maybe even faster)
It would be very convenient to be able to set the replay position clicken the tape bar.
I would like to be able to load in background images.
The renderer shouldnt care about the order of particles. (currently you can see wich particle is above)
You should divide Attraction into 3 separate apps and describe the msg-interface.
Write a MessageCenter/ApplicationComposer app.
Evolve Attraction to be a speech recognition system.
Evolve Attraction towards being a strategy game.
You should call the next version Addiction
The settings in the control-panel should be saved.
other, please describe...

I found a Bug!

Please feel free to make any comment:

I think this survey is a good idea.

Thanks!

fratricide logo

this html was done with
[h.Scribe Version 0.1.2 - ©1997 C. Papazissis](free)
Thanks to the author! <©> fratricide, 1997
created by Nicolas Fischer