Difference between revisions of "CoreWML"

From The Battle for Wesnoth Wiki
(The [core] Tag)
(Common Pitfalls: Mostly reformatting, also remove the reference to _info.cfg)
(7 intermediate revisions by 4 users not shown)
Line 2: Line 2:
  
 
This page describes how the core is displayed in the "Load Core" menu, and how it works.
 
This page describes how the core is displayed in the "Load Core" menu, and how it works.
Cores are to be defined in a file called cores.cfg in you add-ons base directory. An add-on containing only a core does not need an _main.cfg, cores are loaded prior to that by looking for cores.cfg.
+
Cores are to be defined in a file called cores.cfg in your add-ons base directory. An add-on containing only a core does not need a _main.cfg, cores are loaded prior to that by looking for cores.cfg. To publish the add-on from within wesnoth a _main.cfg is needed but it can be an empty one. '''_main.cfg should NOT be the same file as what is defined under [core] path or everything will be loaded twice!'''
  
Other add-ons, which rely on a specifc core, need to have it mentioned in the _server.pbl / _info.cfg.
 
  
 
==The [core] Tag==  
 
==The [core] Tag==  
{{DevFeature1.13|x}}
+
{{DevFeature1.13|0}}
  
 
The following keys and tags are recognized in '''[core]''' tags:
 
The following keys and tags are recognized in '''[core]''' tags:
 
* '''id''': the internal core identifier used to load only core specific add-ons.
 
* '''id''': the internal core identifier used to load only core specific add-ons.
* '''icon''': the image displayed in the core selection menu
+
* '''image''': the icon displayed in the core selection menu. It should be part of the main game.
 
* '''name''': (translatable) name displayed in the core selection menu
 
* '''name''': (translatable) name displayed in the core selection menu
* '''image''': the image shown in the information pane when this core is selected in the core selection menu (typically a transparent, 350×350 pixels portrait)
 
 
* '''description''': (translatable) text shown in the information pane when this core is selected in the core selection menu
 
* '''description''': (translatable) text shown in the information pane when this core is selected in the core selection menu
 
* '''rank''': a number that determines the order of cores in the core selection menu.  Lower ''rank'' cores appear earlier, with unranked cores at the end. The default core has rank 5.
 
* '''rank''': a number that determines the order of cores in the core selection menu.  Lower ''rank'' cores appear earlier, with unranked cores at the end. The default core has rank 5.
 
* '''path''': the path to the core's directory or initial config file. E.g. ''~add-ons/my_core/load.cfg''. This config file (or the config files in that directory) should load things similar to the file data/_main.cfg in mainline.
 
* '''path''': the path to the core's directory or initial config file. E.g. ''~add-ons/my_core/load.cfg''. This config file (or the config files in that directory) should load things similar to the file data/_main.cfg in mainline.
 +
 +
== Common Pitfalls ==
 +
* Similar to [campaign] tags, [core] tags are read before the core is loaded. Thus, [binary_path]s and translations defined in the file (or directory) set by '''path''' are not yet available. You must make sure that the icon '''image''' is available while another core is in use (the second method is recommended):
 +
*# Use an image from the default core
 +
*# Write the full path to the image, e.g. ''data/add-ons/my_core/images/icon-for-core-selection-menu.png''
 +
*# Set up the binary paths to be in use even when your core is not, by setting them in _main.cfg (untested).
 +
* In case the core contains translations, use the third method to set up the '''[textdomain]''', so that the translation for the core's description and name are available.
 +
* Only add-ons designed for this core will be available.
 +
* Add-ons created for a custom core need to specify that they are not to be used with the default core but this one. For that, one specifies the '''core''' in the _server.pbl, see [[PblWML]]. Because of this, the _server.pbl must be present if your add-on uses a custom core.
 +
* A new core will contain absolutely nothing. The engine may crash in a few cases, when it looks for something which isn't there ([https://github.com/wesnoth/wesnoth/issues/3702 known cases]). Best to include similar things like the file data/_main.cfg in the default core does.
 +
* One can include files from the default core with the [[PreprocessorRef#Inclusion_directive_.7B.7D|preprocessor's inclusion directive]]. E.g. ''{data/multiplayer/scenarios/}'' to include MP scenarios from the default core. No need to copy everything.
  
 
== See Also ==
 
== See Also ==

Revision as of 01:51, 25 October 2019

[edit]WML Tags

A:

abilities, about, achievement, achievement_group, add_ai_behavior, advanced_preference, advancefrom, advancement, advances, affect_adjacent, ai, allied_with, allow_end_turn, allow_extra_recruit, allow_recruit, allow_undo, and, animate, animate_unit, animation, aspect, attack (replay, weapon), attack_anim, attacks (special, stats), avoid;

B:

base_unit, background_layer, berserk, binary_path, break, brush;

C:

campaign, cancel_action, candidate_action, capture_village, case, chance_to_hit, change_theme, chat, checkbox, choice, choose, clear_global_variable, clear_menu_item, clear_variable, color_adjust, color_palette, color_range, command (action, replay), continue, credits_group, criteria;

D:

damage, death, deaths, default, defend, defends, defense, delay, deprecated_message, destination, difficulty, disable, disallow_end_turn, disallow_extra_recruit, disallow_recruit, do, do_command, drains, draw_weapon_anim;

E:

editor_group, editor_music, editor_times, effect, else (action, animation), elseif, endlevel, end_turn (action, replay), enemy_of, engine, entry (credits, options), era, event, experimental_filter_ability, experimental_filter_ability_active, experimental_filter_specials, extra_anim;

F:

facet, facing, fake_unit, false, feedback, female, filter (concept, event), filter_adjacent, filter_adjacent_location, filter_attack, filter_attacker, filter_base_value, filter_condition, filter_defender, filter_enemy, filter_location, filter_opponent, filter_own, filter_owner, filter_radius, filter_recall, filter_second, filter_second_attack, filter_self, filter_side, filter_student, filter_vision, filter_weapon, filter_wml, find_path, fire_event, firststrike, floating_text, found_item, for, foreach, frame;

G:

game_config, get_global_variable, goal, gold, gold_carryover;

H:

harm_unit, has_ally, has_attack, has_unit, has_achievement, have_location, have_unit, heal_on_hit, heal_unit, healed_anim, healing_anim, heals, hide_help, hide_unit, hides;

I:

idle_anim, if (action, animation, intro), illuminates, image (intro, terrain), init_side, insert_tag, inspect, item, item_group;

J:

jamming_costs, join;

K:

kill, killed;

L:

label, language, leader, leader_goal, leadership, leading_anim, levelin_anim, levelout_anim, lift_fog, limit, literal, load_resource, locale, lock_view, lua;

M:

male, menu_item, message, micro_ai, missile_frame, modification, modifications, modify_ai, modify_side, modify_turns, modify_unit, modify_unit_type, move, move_unit, move_unit_fake, move_units_fake, movement_anim, movement costs, movetype, multiplayer, multiplayer_side, music;

N:

not, note;

O:

object, objective, objectives, on_undo, open_help, option, options, or;

P:

part, petrifies, petrify, place_shroud, plague, poison, post_movement_anim, pre_movement_anim, primary_attack, primary_unit, print, progress_achievement, put_to_recall_list;

R:

race, random_placement, recall (action, replay), recalls, recruit, recruit_anim, recruiting_anim, recruits, redraw, regenerate, remove_event, remove_item, remove_object, remove_shroud, remove_sound_source, remove_time_area, remove_trait, remove_unit_overlay, repeat, replace_map, replace_schedule, replay, replay_start, reset_fog, resistance (ability, unit), resistance_defaults, resource, return, role, rule;

S:

save, scenario, screen_fade, scroll, scroll_to, scroll_to_unit, secondary_attack, secondary_unit, section, select_unit, sequence, set_achievement, set_extra_recruit, set_global_variable, set_menu_item, set_recruit, set_specials, set_variable, set_variables, sheath_weapon_anim, show_if (message, objective, set_menu_item), show_objectives, side, skirmisher, slider, slow, snapshot, sound, sound_source, source (replay, teleport), special_note, specials, split, stage, standing_anim, statistics, status, store_gold, store_items, store_locations, store_map_dimensions, store_reachable_locations, store_relative_direction, store_side, store_starting_location, store_time_of_day, store_turns, store_unit, store_unit_defense, store_unit_defense_on, store_unit_type, store_unit_type_ids, store_villages, story, swarm, sub_achievement, switch, sync_variable;

T:

target, team, teleport (ability, action), teleport_anim, terrain, terrain_defaults, terrain_graphics, terrain_mask, terrain_type, test, test_condition, test_do_attack_by_id, text_input, textdomain, theme, then, tile, time, time_area, topic, toplevel, trait, transform_unit, traveler, true, tunnel;

U:

unhide_unit, unit, unit_overlay, unit_type, unit_worth, units, unlock_view, unpetrify, unstore_unit, unsynced;

V:

value, variable, variables, variant, variation, victory_anim, village, vision_costs, volume;

W:

while, wml_message, wml_schema;

Z:

zoom;

This page describes how the core is displayed in the "Load Core" menu, and how it works. Cores are to be defined in a file called cores.cfg in your add-ons base directory. An add-on containing only a core does not need a _main.cfg, cores are loaded prior to that by looking for cores.cfg. To publish the add-on from within wesnoth a _main.cfg is needed but it can be an empty one. _main.cfg should NOT be the same file as what is defined under [core] path or everything will be loaded twice!


The [core] Tag

(Version 1.13.0 and later only)

The following keys and tags are recognized in [core] tags:

  • id: the internal core identifier used to load only core specific add-ons.
  • image: the icon displayed in the core selection menu. It should be part of the main game.
  • name: (translatable) name displayed in the core selection menu
  • description: (translatable) text shown in the information pane when this core is selected in the core selection menu
  • rank: a number that determines the order of cores in the core selection menu. Lower rank cores appear earlier, with unranked cores at the end. The default core has rank 5.
  • path: the path to the core's directory or initial config file. E.g. ~add-ons/my_core/load.cfg. This config file (or the config files in that directory) should load things similar to the file data/_main.cfg in mainline.

Common Pitfalls

  • Similar to [campaign] tags, [core] tags are read before the core is loaded. Thus, [binary_path]s and translations defined in the file (or directory) set by path are not yet available. You must make sure that the icon image is available while another core is in use (the second method is recommended):
    1. Use an image from the default core
    2. Write the full path to the image, e.g. data/add-ons/my_core/images/icon-for-core-selection-menu.png
    3. Set up the binary paths to be in use even when your core is not, by setting them in _main.cfg (untested).
  • In case the core contains translations, use the third method to set up the [textdomain], so that the translation for the core's description and name are available.
  • Only add-ons designed for this core will be available.
  • Add-ons created for a custom core need to specify that they are not to be used with the default core but this one. For that, one specifies the core in the _server.pbl, see PblWML. Because of this, the _server.pbl must be present if your add-on uses a custom core.
  • A new core will contain absolutely nothing. The engine may crash in a few cases, when it looks for something which isn't there (known cases). Best to include similar things like the file data/_main.cfg in the default core does.
  • One can include files from the default core with the preprocessor's inclusion directive. E.g. {data/multiplayer/scenarios/} to include MP scenarios from the default core. No need to copy everything.

See Also