Version 0.2

definitions/palabritas.md

@@ -0,0 +1,243 @@
+# Palabritas: cuentito's language
+
+`cuentitos` is a narrative engine that includes its own language for writers to create dynamic storytelling: `palabritas`.
+
+In this document I will introduce you to `palabritas`.
+
+## Basics
+
+You can start by writing small pieces of text. Each newline will prompt the user to continue.
+
+```cuentitos
+You've just arrived in the bustling city, full of excitement and anticipation for your new job. 
+The skyline reaches for the clouds, and the sounds of traffic and people surround you. 
+As you take your first steps in this urban jungle, you feel a mix of emotions, hoping to find your place in this new environment.
+```
+
+Now, you can add options after an event by indenting with two spaces and starting the line for each option with an asterisk `*`
+
+```cuentitos
+[...]
+As you take your first steps in this urban jungle, you feel a mix of emotions, hoping to find your place in this new environment.
+  * I take a walk through a nearby park to relax and acclimate to the city.
+  * I visit a popular street market to experience the city's unique flavors and energy.
+```
+
+You can now start a new narrative path by indenting with 2 spaces and writing the next text bits.
+
+```cuentitos
+  [...]
+  * I take a walk through a nearby park to relax and acclimate to the city.
+    As you stroll through the nearby park, the soothing sounds of rustling leaves and chirping birds help calm your senses. 
+    You find a quiet bench to sit on, taking a moment to breathe deeply and gather your thoughts. 
+    This serene oasis gives you the confidence to face the challenges ahead as you acclimate to your new life in the bustling city.
+```
+
+## Probabilistic One-Off's
+
+An interesting feature of cuentitos is that you can use probability to render different things in the story. For example, in our case, we can use probability to have someone sitting on the bench or not.
+
+```cuentitos
+    [...]
+    You find a quiet bench to sit on, taking a moment to breathe deeply and gather your thoughts. 
+    (50%) A solitary figure sits on the bench, engrossed in a book, seemingly unfazed by the surrounding city noise.
+    This serene oasis gives you the confidence to face the challenges ahead as you acclimate to your new life in the bustling city.
+    [...]
+```
+
+This will make it so that half of the time the solitary figure is there sitting there, and half of the time, they're not. Whenever you have a one off text with probability, you can directly write said probability as a percentage. So in this case there is a `50%` chance that this text will be rendered. We call this the `one-off percentage notation`.
+
+Another way is to use the `one-off probability notation`, that uses a range from 0 to 1 to determine how probable that event is. In this case, we'd have to use `0.5`. 
+
+```cuentitos
+    [...]
+    You find a quiet bench to sit on, taking a moment to breathe deeply and gather your thoughts. 
+    (0.5) A solitary figure sits on the bench, engrossed in a book, seemingly unfazed by the surrounding city noise.
+    This serene oasis gives you the confidence to face the challenges ahead as you acclimate to your new life in the bustling city.
+    [...]
+```
+
+
+In practice, both notations are similar and it's mostly up to you which one to use, the only difference is the precission: percentage notation only supports integers, while probability notation supports real numbers (floats). You can't do `55.5%`, but you can do `0.555`.
+
+You could add options on probabilistic branches, but let's keep going for now.
+
+## Probabilistic Buckets
+
+Another interesting feature is the ability to create `probabilistic buckets`.
+
+A bucket is a set of probable paths that the engine will pick one every time is asked to render that bucket. Let's do a probabilistic bucket with the second option.
+
+```cuentitos
+  * I visit a popular street market to experience the city's unique flavors and energy.
+    (50%) At the bustling street market, you discover a food stand offering mouthwatering delicacies. 
+      As you sample the delicious fare, you strike up a conversation with the enthusiastic vendor.
+      It's a welcome distraction from the noise around you.
+    (20%) As you try to navigate the crowded market, you're drawn to the entrancing melody of a street musician. 
+      The captivating sound creates a soothing bubble, momentarily transporting you away from the city's noise. 
+      You take a moment to appreciate the beauty of the music, feeling a connection to the artist and the vibrant energy they bring to the urban landscape.
+    (30%) Wandering the market, you stumble upon a hidden alley adorned with vibrant street art. 
+      Each colorful mural tells a different story, capturing your imagination and sparking your creativity. 
+      This unexpected oasis of visual tranquility provides a respite from the chaos of the city, inspiring you to explore more of the urban canvas and the stories it holds.
+```
+
+In this example, we added an indentation from the option and ten added 3 narrative paths with probabilities expressed in percentage notation. Every time you indent and add probabilities you're effectively creating a bucket.
+
+Notice that the sum of the probabilities is `100%`. This is a requirement if using `percentage notation` in a bucket, the compiler will fail if you have a different sum. The same will happen if you use `probability notation`, the sum has to be `1`, otherwise the compiler will throw an error.
+
+There is another useful notation available on buckets that is called the `frequency notation`, where you can set the frequency of each event. The probability will be calculated as the frequency over the sum of the frequencies of all the events in the bucket. There is no requirement to keep a consistent sum of frequencies, the probability of all events will adjust as you add more or change the existing ones.
+
+```cuentitos
+  * I visit a popular street market to experience the city's unique flavors and energy.
+    (50) At the bustling street market, you discover a food stand offering mouthwatering delicacies. 
+      As you sample the delicious fare, you strike up a conversation with the enthusiastic vendor.
+      It's a welcome distraction from the noise around you.
+    (2) As you try to navigate the crowded market, you're drawn to the entrancing melody of a street musician. 
+      The captivating sound creates a soothing bubble, momentarily transporting you away from the city's noise. 
+      You take a moment to appreciate the beauty of the music, feeling a connection to the artist and the vibrant energy they bring to the urban landscape.
+    (500) Wandering the market, you stumble upon a hidden alley adorned with vibrant street art. 
+      Each colorful mural tells a different story, capturing your imagination and sparking your creativity. 
+      This unexpected oasis of visual tranquility provides a respite from the chaos of the city, inspiring you to explore more of the urban canvas and the stories it holds.
+
+```
+Given what we just said, which event is more probable of the three?
+
+The hidden alley! Let's see why:
+
+The sum of frequencies is `50 + 2 + 500 = 552`, then the probability of the deli stand is `50 / 552 ~= 0.09`, the probability of the musician is `2 / 552 ~= 0.003` and the probability of the hidden alley is `500 / 552 ~= 0.9`. So 9 out of 10 times we'll get the alley.
+
+### Probability of Options
+
+Probability can be applied to pretty much everything in `cuentitos`, including options. Let's explore that.
+
+You can add a chance for an option to show up by adding the probability after the asterisk:
+
+```cuentitos
+      [...]
+      You take a moment to appreciate the beauty of the music, feeling a connection to the artist and the vibrant energy they bring to the urban landscape.
+        * (50%) I leave two dollars to the artist.
+          The musician smiles and nods thanking you.
+        * I nod when the musician looks my way, to show I really enjoy the music.
+      [...]
+```
+
+If a choice doesn't have probability set, the probability of it showing up is 100%.
+
+In this case there is a 50% chance the user will see the option to leave two dollars to the musician. So half of the times he'll support the artist economically, and half just nod.
+
+#### Options bucket
+
+If all the options in an indentation level are probabilistic, then a bucket is created.
+
+This means that only one of those options will show up, respecting the probability rules.
+
+```cuentitos
+    (500) Wandering the market, you stumble upon a hidden alley adorned with vibrant street art. 
+      Each colorful mural tells a different story, capturing your imagination and sparking your creativity. 
+        * (50%) I grab my phone and take pictures of the murals.
+        * (50%) I keep walking, even if the murals look good, the darkness of the alley is unsettling.
+```
+
+In this case, only one of the options will show up, each one with a 50% chance.
+
+## Reacting to State
+
+Up until this point, we've not used the game state to setup conditions. So let's do that now. We'll start writing from the root indentation level again. This texts will show up when the previous section is navigated until there is no more text to show. It will automatically backtrack to the root if no texts display in any indentation level.
+
+```cuentitos
+Feeling mentally and physically exhausted from the day's adventures, you decide it's time to head back to your hotel.
+As you enter the peaceful sanctuary of your room, you take a deep breath, relieved to have a quiet space where you can recharge and prepare for the challenges ahead.
+
+The sun shines bright through the window.
+  req time_of_day !night
+The moonlight gives the room a peaceful tone.
+  req time_of_day night
+```
+
+In this case, we're putting conditions to these two lines of text. They will only show up if the `time_of_day` variable value satisfies the conditions. The first one will show if time of day is not `night`, the second one, will show when time of day is `night`.
+
+Check the `Configuration` section to learn about variables.
+
+In this case, the requirements are mutually exclusive, only one will show at a time. But that's not a requirement. You could have multiple lines with different requirements and have them show one after the other if the conditions are satisfied.
+
+```cuentitos
+The sun shines bright through the window.
+  req time_of_day !night
+The moonlight gives the room a peaceful tone.
+  req time_of_day night
+You start to think about all the stuff you need to do tomorrow.
+  req time_of_day_night
+That makes you feel overwhelmed.
+  req time_of_day_night
+  req energy <10
+```
+
+These two new lines will only show at night, after `The moonlight gives...`. The last one only if the player is low on energy.
+
+You can also add requirements to options.
+
+```cuentitos
+[...]
+That makes you feel overwhelmed.
+  req time_of_day_night
+  req energy <10
+  * I make some tea
+    req item tea
+    A good cup of tea is always good to regulate after the sensory overload of the city.
+  * I go to bed
+    Feeling depleted of spoons, you go right back to bed.
+  * I call my parents
+    req energy >10
+```
+
+In this case, to make tea you need an `item` with identifier `tea` in the inventory.
+You also need more than `10` points of energy to call your parents.
+
+### Conditional probability changes
+
+You can change the probability of a text of option if a given condition is met by using the `freq` command.
+
+```cuentitos
+[...]
+  * I call my parents
+    req energy >10
+    (30) The phone rings twice, and dad picks up.
+      req energy>20
+    (10) The phone rings twice, and mom picks up.
+      req energy>20
+      freq time_of_day night 100
+    (40) The phone rings ten times, nobody is at home.
+```
+
+Let's analyse this situation:
+
+ * If the player has `energy` between `11` and `20`, nobody picks up, because the condition of `energy>20` is not met, so mom and dad will not pickup.
+ * If `energy` is `21` or more and `time_of_day` is not `night`, there are more chances that dad will pick up than mom (frequency `30` for dad, vs `10` for mom).
+ * If `energy` is `21` or more and `time_of_day` is `night`, it is very likely that mom will pick up, because the frequency is `110` (vs `30` for dad, and `40` for no one).
+
+In this way we can create very complex condition sets and frequency alterations that we can use to modify the behavior of our story. This is incredibly useful to create games that feel alive, in this example, the mother of the player works all day outside the house, while the dad takes care of the home during the day. 
+
+Conditions and probability modifications can be used to express rules of the world and its randomness to successfully represent a world that is more complex, alive and random than simple rule-based ones.
+
+The `freq` command can take negative numbers too, to reduce the frequency instead of increasing it.
+
+```cuentitos
+    (10) The phone rings twice, and mom picks up.
+      req energy>20
+      freq time_of_day !night -100
+```
+
+If the frequency ends up being 0 or less, the affected element will not be considered. In this case, mom would not pickup the phone at all unless it's night time.
+
+## Changing State
+
+## String interpolation
+
+## Configuration
+### Variables
+#### Bool
+#### Integer
+#### Float
+#### Enum
+## Reputations
+## Items

examples/story-example.cuentitos

@@ -0,0 +1,48 @@
+You've just arrived in the bustling city, full of excitement and anticipation for your new job. 
+The skyline reaches for the clouds, and the sounds of traffic and people surround you. 
+As you take your first steps in this urban jungle, you feel a mix of emotions, hoping to find your place in this new environment.
+	* I take a walk through a nearby park to relax and acclimate to the city.
+    As you stroll through the nearby park, the soothing sounds of rustling leaves and chirping birds help calm your senses. 
+    You find a quiet bench to sit on, taking a moment to breathe deeply and gather your thoughts. 
+    (50/100) A solitary figure sits on the bench, engrossed in a book, seemingly unfazed by the surrounding city noise.
+    This serene oasis gives you the confidence to face the challenges ahead as you acclimate to your new life in the bustling city.
+	* I visit a popular street market to experience the city's unique flavors and energy.
+    (50) At the bustling street market, you discover a food stand offering mouthwatering delicacies. 
+      As you sample the delicious fare, you strike up a conversation with the enthusiastic vendor.
+      It's a welcome distraction from the noise around you.
+    (2) As you try to navigate the crowded market, you're drawn to the entrancing melody of a street musician. 
+      The captivating sound creates a soothing bubble, momentarily transporting you away from the city's noise. 
+      You take a moment to appreciate the beauty of the music, feeling a connection to the artist and the vibrant energy they bring to the urban landscape.
+        * (50%) I leave two dollars to the artist.
+          The musician smiles and nods thanking you.
+        * I nod when the musician looks my way, to show I really enjoy the music.
+    (500) Wandering the market, you stumble upon a hidden alley adorned with vibrant street art. 
+      Each colorful mural tells a different story, capturing your imagination and sparking your creativity. 
+        * (50%) I grab my phone and take pictures of the murals.
+        * (50%) I keep walking, even if the murals look good, the darkness of the alley is unsettling.
+      This unexpected oasis of visual tranquility provides a respite from the chaos of the city, inspiring you to explore more of the urban canvas and the stories it holds.
+
+Feeling mentally and physically exhausted from the day's adventures, you decide it's time to head back to your hotel.
+As you enter the peaceful sanctuary of your room, you take a deep breath, relieved to have a quiet space where you can recharge and prepare for the challenges ahead.
+The sun shines bright through the window.
+  req time_of_day !night
+The moonlight gives the room a peaceful tone.
+  req time_of_day night
+You start to think about all the stuff you need to do tomorrow.
+  req time_of_day_night
+That makes you feel overwhelmed.
+  req time_of_day_night
+  req energy <10
+  * I make some tea
+    req item tea
+    A good cup of tea is always good to regulate after the sensory overload of the city.
+  * I go to bed
+    Feeling depleted of spoons, you go right back to bed.
+  * I call my parents
+    req energy >10
+    (30) The phone rings twice, and dad picks up.
+      req energy>20
+    (10) The phone rings twice, and mom picks up.
+      req energy>20
+      freq time_of_day morning 100
+    (40) The phone rings ten times, nobody is at home.