[A (short) Tutorial on Bars]

[mjshi]

Preamble
Some of the information here probably is already known by (more experienced) programmers, but as a beginner in the Ren'Py scripting language, I had wanted to use bars and values, but couldn't find a comprehensive tutorial for them (the only tutorial that ever came close was Aleema's tutorial for a preferences bar). Thus, in all of my inexperienced and verbose glory I decided to make this tutorial to spare other aspiring programmers the frustration.
As this is my first tutorial, feel free to correct me if any of this information is wrong.

Contents and Links
- Documentation
- Make a bar using the theme's preset graphics
- Make a bar using custom images
- Display that bar using screens
- Have a smooth "sliding" animation when value changes using regular Ren'py language
- Use both horizontal and vertical bars
- Adjustable values of bars

• alternative method- replace StaticValue with: bar value VariableValue("variable", maximum)

- Bars on the Preferences Screen

The Code for Bar Creation
Old:
This was found entirely in a forum search, and I had no idea of this code's existence until, say, two weeks ago.
Below is the code for a nonadjustable bar. To create an adjustable bar, see the link above labeled Adjustable Bars.
NOTE: The code below cannot be directly inserted into the script, you must define a few things first (read: Using the Code of (bar) Creation)

Code: Select all

$ ui.bar(maximum, value, xmaximum=length of bar, ymaximum=height of bar, left_bar=Frame("image1.png", 10, 0), right_bar=Frame("image2.png", 10, 0), xalign=1.0, yalign=0.0, thumb="slider_thing.png", thumb_shadow="selfexplanitory.png")

**New (recommended):
Same code as above, but in a newer screen language. Only most common style properties listed, for more style properties please view this, this, and this.

Code: Select all

bar value StaticValue(value, maximum):
    xalign 1.0 yalign 0.0
    xmaximum length of bar
    ymaximum height of bar
    left_bar Frame("image1.png", 10, 0)
    right_bar Frame("image2.png", 10, 0)
    left_gutter 0
    right_gutter 0
    thumb "slider_thing.png"
    thumb_shadow "selfexplanitory.png"

Using the Code of (bar) Creation
An explanation of properties:

• ui.bar .:. The 'bar' can be replaced with 'vbar' to create a vertical bar instead of a horizontal one.
  **bar .:. As it appears in the newer screen language. Can also be replaced by vbar to create a vertical bar.
  **StaticValue() .:. "Allows a value to be specified statically." Can be replaced VariableValue("variable", maximum) to allow sliding.
  maximum .:. This can be replaced with a variable of your choice or even a constant number to serve as the maximum value the bar will show (everything above= same 'full' appearance)
  value .:. This can be replaced with a (second) variable that indicates the value that the bar represents. For example, a maximum of 100 and a value of 50 would make the bar appear about 50% full, or half full (half empty :P)
  xmaximum and ymaximum .:. The length and height of your bar, respectively. If you're using a predefined image, it's imperative that you set this to the dimensions of that image.
  left_bar .:. The "left side" of your bar if you're using a horizontal bar. Usually, what the bar "fills up with", (**the following does not apply in the new screen language) unless if you're using a vertical bar (see Horizontal and Vertical Bar Disambiguation). Read on for explanations of the Frame property.
  right_bar .:. The "right side" of your bar if you're using a horizontal bar. Usually, the "empty part" of the bar.
  left/right_gutter .:. The bar "gutter", usually only used if you have a bar that has some fancy framing. Alternatively for vertical bars, you can use top/bottom_gutter.
  Frame("image.png", 10, 0) .:. Aleema's explanation on Frame() - it's the big heading "Using Frames" and has a helpful visual aid. Mentally replace "Dialog boxes" with "Bars" in your head, the Frame property works pretty much in the same way.
  xalign and yalign .:. Float numbers (basically, a number between 0.0 and 1.0) that determine where the bar is going to show up. 0.0 on xalign is left and 1.0 is right. 0.0 on yalign is the top and 1.0 is the bottom. The only way to really get the bar exactly where you want is to launch the game and experiment with the code.
  thumb .:. The thumb is basically the slider-thing. Which slider thing? Obviously, the slider thing that you see so often in the preferences menu. You can define an image, or you can set it to None since the slider thing is just something to emphasize where the bar ends and is actually kind of decorative anyway. But it looks nice.
  thumb_shadow .:. Self explanatory, this is just an image that's put under the thumb to make it stand out even more. Again, you can set this to None if you choose to.

Displaying the Bar
Now with all of that defining done (phew) you can get to the business of actually making it appear, on a screen, as an overlay, and show and hide it as many times as you want.

Here's how to make the screen, and don't forget to define any variables in an init block.

Code: Select all

init:
    $ barvariable = 0

screen thebar:
    $ ui.bar(100, barvariable, xmaximum=400, ymaximum=15, left_bar=Frame("image.png", 10, 0), right_bar=Frame("image2.png", 10, 0), xalign=0.0, yalign=0.0, thumb="thumb.png", thumb_shadow=None)

## Or:

screen thebar:
    bar value StaticValue(barvariable, 100):
        xalign 0.0 yalign 0.0 
        xmaximum 400 
        ymaximum 15
        left_bar Frame("image.png", 10, 0) 
        right_bar Frame("image2.png", 10, 0)
        thumb "thumb.png" 
        thumb_shadow None

To show and hide the bar, simply type "show screen thebar" and "hide screen thebar", receptively, in your script. To change the value of the bar, simply change the value of the variable, or in this case, "barvariable". To make the bar seem to 'slide' up/down when the value changes, read on.

Value Changes: The Animation


Here is a working demo.

To make a bar seem to slide like the image above, we will have to take advantage of Ren'py's "while" and "pause" statements.

The animation's logic is based on something like this: the while statement makes something loop over and over again until a condition is fulfilled (in this case, a variable increasing or decreasing by one until it equals the variable that is counting how many times the while statement has looped) , and the pause statement will give the visual effect of the bar seeming to 'slide' into place.

Step 1: Define a 'counting' variable (can be named anything, I named it "counting" to keep things simple) to keep track of how many times the while statement will repeat. Set it to zero right before the while statement every time you plan to use this sliding animation thing.
Step 2: Create a while statement, which is the basis for the sliding motion
Step 3: Add a "pause 0.01" to allow the player to view the bar in all of its sliding magnificence

The final code should look something like this:

Code: Select all

$ counting = 0

while counting < 40:
    $ variable += 1
    $ counting += 1
    pause 0.01

"Continue script here"

In the example above, we set the "while" statement to check for the value of "counting". We are increasing the value of "variable" by 40, and so we set the condition of the "while" statement to "< 40".

Alternatively, you can try the AnimatedValue property.

Horizontal and Vertical Bar Disambiguation **does not apply in new screen language
While your handy $ ui.bar(...) is horizontal, maybe people want some vertical bars in here. However, to make a vertical bar, there are some slight changes (besides the obvious changes to xmaximum and ymaximum values to make it more tall than, well, horizontal) that you need to make to your bar images.



No, the other bar.



Yes, that one. So anyway, $ ui.bar(...)'s offending horizontalness can be changed into a vertical bar... by typing a 'v' in front of the word 'bar'. $ ui.vbar(...). Whala.
However, there is one slight thing that happens to horizontal bars when they suddenly turn vertical. Ren'py (probably in an effort to save resources) defined a vertical bar as a horizontal bar... rotated in a weird way, with the images... flipped, I guess? See for yourself:

Same bars... or not.

Screenshot_2.png (3.71 KiB) Viewed 31783 times

In order to counter this, when making a vertical bar, please proceed to disregard the notion that left_bar is "full" and right_bar is "empty". In a vertical bar, left_bar is "empty" while right_bar seems to be "full". Then again this is just an image swap which is seriously a no sweat, 5-second copy-paste operation but I have no idea why I'm rambling on about this

Conclusion
Thus concludes this short tutorial on bars. I hope that my information isn't too terribly wrong and that future updates won't make my tutorial obsolete (currently written during Ren'py 6.17.6).
Happy, er, bar-ing.

[PyTom]

This code is kind of old fashioned. The ui functions are pre-screens code, and while they work with screens, as of 6.18 the screen code should be significantly faster.

Here's a port of your example.

Code: Select all

screen thebar:
    bar value StaticValue(barvariable, 1000):
        xalign 0.0 yalign 0.0 
        xmaximum 400 
        ymaximum 15
        left_bar Frame("image.png", 10, 0) 
        right_bar Frame("image2.png", 10, 0)
        thumb "thumb.png" 
        thumb_shadow None

[mjshi]

I was unaware of this, seeing as there was... not much in terms of threads to go on.

Alright, I've updated the code, thanks Pytom ^_^

Edit: Just wondering, is it possible to directly adjust a variable through a bar?
Though if it isn't possible, I can understand why. Many variables would become pretty useless if it could be controlled by the player.

[SundownKid]

Bars can adjust data, yes.

Here is the current up to date info on bar code: http://www.renpy.org/doc/html/screens.html#bar, http://www.renpy.org/doc/html/screens.html#vbar

You use "adjustment" when you want to make the bar able to change a variable.

[mjshi]

@SundownKid:
Thank you for your reply, but what I meant was a normal variable's value being affected by the bar, whereas ui.adjustment() is more of something...else, whose value can't really be changed by normal variable operations. I was already aware of the existence of ui.adjustment() from wiki-browsing :P

[PyTom]

You use "adjustment" when you want to make the bar able to change a variable.

I think the preferred way is something like:

Code: Select all

bar value VariableValue("foo", 100)

[JaxxyLupei]

I had been searching for something like this for AGES and I never thought to look in the Cookbook forum. I found a simple HP bar screen someone posted, but could not for the life of me, figure out how to use my own graphics for it. This is a lot better. It took some tinkering (and some frustration because I'm a n00b when it comes to Python and other coding) This helped a bunch!

[mjshi]

@JaxxyLupei: I'm glad it was able to help ^_^

And don't worry, you'll get better at coding- the more you use it, the more familiar the it will be to you (It's like learning a foreign language xD).

If you ever need any help, the Ren'Py questions and announcements forum is always open. Otherwise-- I wish you luck with your projects :3

[JaxxyLupei]

Hello! I'm back with a question. I want to utilize the animation into my game, will it be compatible with http://lemmasoft.renai.us/forums/viewto ... 51&t=22147 this love meter bar? I was looking at the script of the working demo and I'm not sure how it could translate to the love meter code.

[CSV]

Oh, this looks so useful. *bookmarks* Thank you for the tutorial, I never really understood how bars were meant to work.

[mjshi]

@CSV: No problem ^^ glad I was able to help~

@JaxxyLupei:
Yes, the "animation" part should be completely compatible, especially since they're both in core Ren'Py code. Her love meter bars are just in an older ui screen language. In her example:

Then, when you want to SHOW the addition of points on the bar during the story, you pop in this bit of code:
Code:

Code: Select all

    $ show_giselle=True 
    # This makes the Meter appear.

    pause 0.5
    # This makes the meter sit there for half a second, so that when the points 
    # are added, the player can actually 'see' the meter extend.

    $ giselle_love+=50
    #This adds points to the meter. 
    
#.... etc
    $ show_giselle=True
    # This is a Refresh that shows the increase in points ON the meter.

    $ renpy.pause()
    #This keeps the bar visible until the player hits a key. 

    hide text with dissolve
    # This hides the Text. 

    $ show_giselle=False
    # This hides the Meter. 

During the

Code: Select all

    $ show_giselle=True 
    # This makes the Meter appear.

    pause 0.5
    # This makes the meter sit there for half a second, so that when the points 
    # are added, the player can actually 'see' the meter extend.

    $ giselle_love+=50
    #This adds points to the meter. 

just change it to

Code: Select all

    $ show_giselle=True 
    # This makes the Meter appear.

    pause 0.5
    # This makes the meter sit there for half a second, so that when the points 
    # are added, the player can actually 'see' the meter extend.
 
    $ counting = 0

    while counting < 50:
        $ giselle_love+=1
        #This adds points to the meter, until giselle_love reaches +50, then exits the loop.
        pause 0.01

"Continue script here"

[JaxxyLupei]

Thank you so much! That worked pretty well.

[abbylee]

Bars can adjust data, yes.

Here is the current up to date info on bar code: http://www.renpy.org/doc/html/screens.html#bar, http://www.renpy.org/doc/html/screens.html#vbar

You use "adjustment" when you want to make the bar able to change a variable.

Hey, SundownKid
Thanks for the sharing. I will test it later.

[017Bluefield]

Is there no way to simulate this pseudo-progressbar effect?
https://jsfiddle.net/mnbishop017/0pq9Lgb6/22/